\input texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename standards.text
+@setfilename standards.info
@settitle GNU Coding Standards
+@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
+@set lastupdate 21 September 1994
@c %**end of header
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
@setchapternewpage off
@ifinfo
-Copyright (C) 1992 Free Software Foundation
+GNU Coding Standards
+Copyright (C) 1992, 1993, 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.
@end ifinfo
@titlepage
-@sp 10
-@titlefont{GNU Coding Standards}
-@author{Richard Stallman}
-@author{last updated 16 May 1992}
-@c Note date also appears below.
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992 Free Software Foundation
+Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
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 Free Software Foundation.
+by the Free Software Foundation.
@end titlepage
@ifinfo
-@node Top, Reading Non-Free Code, (dir), (dir)
+@node Top, Preface, (dir), (dir)
@top Version
-Last updated 16 May 1992.
-@c Note date also appears above.
+Last updated @value{lastupdate}.
@end ifinfo
@menu
+* Preface:: About the GNU Coding Standards
* Reading Non-Free Code:: Referring to Proprietary Programs
* Contributions:: Accepting Contributions
* Change Logs:: Recording Changes
-* Compatibility:: Compatibility with Other Implementations
-* Makefiles:: Makefile Conventions
+* Compatibility:: Compatibility with Other Implementations
+* Makefile Conventions:: Makefile Conventions
* Configuration:: How Configuration Should Work
* Source Language:: Using Languages Other Than C
* Formatting:: Formatting Your Source Code
* Syntactic Conventions:: Clean Use of C Constructs
* Names:: Naming Variables and Functions
* Using Extensions:: Using Non-standard Features
-* Semantics:: Program Behaviour for All Programs
+* System Functions:: Portability and ``standard'' library functions
+* Semantics:: Program Behavior for All Programs
* Errors:: Formatting Error Messages
-* Libraries:: Library Behaviour
+* Libraries:: Library Behavior
* Portability:: Portability As It Applies to GNU
* User Interfaces:: Standards for Command Line Interfaces
* Documentation:: Documenting Programs
* Releases:: Making Releases
@end menu
+@node Preface
+@chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to write portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+Corrections or suggestions regarding this document should be sent to
+@code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
@node Reading Non-Free Code
@chapter Referring to Proprietary Programs
* stmt.c (assign_parms): Round size up for move_block_from_reg.
@end example
-There's no need to describe here the full purpose of the changes or how
-they work together. It is better to put this explanation in comments in
-the code. That's why just ``New function'' is enough; there is a
-comment with the function in the source to explain what it does.
+It's important to name the changed function or variable in full. Don't
+abbreviate them; don't combine them. Subsequent maintainers will often
+search for a function name to find all the change log entries that
+pertain to it; if you abbreviate the name, they won't find it when they
+search. For example, some people are tempted to abbreviate groups of
+function names by writing @samp{* register.el
+(@{insert,jump-to@}-register)}; this is not a good idea, since searching
+for @code{jump-to-register} or @code{insert-register} would not find the
+entry.
+
+There's no need to describe the full purpose of the changes or how they
+work together. It is better to put such explanations in comments in the
+code. That's why just ``New function'' is enough; there is a comment
+with the function in the source to explain what it does.
However, sometimes it is useful to write one line to describe the
overall purpose of a large batch of changes.
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it. What they want from a change log is a
+clear explanation of how the earlier version differed.
+
When you change the calling sequence of a function in a simple
fashion, and you change all the callers of the function, there is no
need to make individual entries for all the callers. Just write in
@node Compatibility
-@chapter Compatibility with Other Implementations
+@chapter Compatibility with Other Implementations
With certain exceptions, utility programs and libraries for GNU should
be upward compatible with those in Berkeley Unix, and upward compatible
then it is not really upward compatible. Try to redesign its
interface.
+Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
When a feature is used only by users (not by programs or command
files), and it is done poorly in Unix, feel free to replace it
completely with something totally different and better. (For example,
but our first priority is usually to duplicate what Unix already
has.
-
-@node Makefiles
-@chapter Makefile Conventions
-
-This chapter describes conventions for writing Makefiles.
-
-@menu
-* Makefile Basics::
-* Standard Targets::
-* Command Variables::
-* Directory Variables::
-@end menu
-
-@node Makefile Basics
-@section General Conventions for Makefiles
-
-Every Makefile should contain this line:
-
-@example
-SHELL = /bin/sh
-@end example
-
-@noindent
-to avoid trouble on systems where the @code{SHELL} variable might be
-inherited from the environment.
-
-Don't assume that @file{.} is in the path for command execution. When
-you need to run programs that are files in the current directory, always
-use @file{./} to make sure the proper file is run regardless of the
-current path.
-
-@node Standard Targets
-@section Standard Targets for Users
-
-All GNU programs should have the following targets in their Makefiles:
-
-@table @samp
-@item all
-Compile the entire program.
-
-@item 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 then run that
-test.
-
-Use @samp{-} before any command for installing a man page, so that
-@code{make} will ignore any errors. This is in case there are systems
-that don't have the Unix man page documentation system installed.
-
-@item 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 @file{.dvi} files here if they are not part of the distribution.
-
-@item 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, @samp{make
-distclean} should leave only the files that were in the distribution.
-
-@item mostlyclean
-Like @samp{clean}, but may refrain from deleting a few files that people
-normally don't want to recompile. For example, the @samp{mostlyclean}
-target for GCC does not delete @file{libgcc.a}, because recompiling it
-is rarely necessary and takes a lot of time.
-
-@item realclean
-Delete 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.
-
-@item TAGS
-Update a tags table for this program.
-
-@item 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 @file{gcc-1.40}.
-
-The easiest way to do this is to create a subdirectory appropriately
-named, use @code{ln} or @code{cp} to install the proper files in it, and
-then @code{tar} that subdirectory.
-
-The @code{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. @xref{Releases}.
-
-@item 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.
-@end table
-
-@node Command Variables
-@section 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 @code{BISON} whose default
-value is set with @samp{BISON = bison}, and refer to it with
-@code{$(BISON)} whenever you need to use Bison.
-
-Each program-name variable should come with an options variable that is
-used to supply options to the program. Append @samp{FLAGS} to the
-program-name variable name to get the options variable name---for
-example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
-this rule, but we keep it because it is standard.)
-
-File-management utilities such as @code{ln}, @code{rm}, @code{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.
-
-Every Makefile should define the variable @code{INSTALL}, which is the
-basic command for installing a file into the system.
-
-Every Makefile should also define variables @code{INSTALL_PROGRAM} and
-@code{INSTALL_DATA}. (The default for each of these should be
-@code{$(INSTALL)}.) Then it should use those variables as the commands
-for actual installation, for executables and nonexecutables
-respectively. Use these variables as follows:
-
-@example
-$(INSTALL_PROGRAM) foo $@{bindir@}/foo
-$(INSTALL_DATA) libfoo.a $@{libdir@}/libfoo.a
-@end example
-
-@noindent
-(Always use a file name, not a directory name, as the second argument.
-Use a separate command for each file to be installed.)
-
-@node Directory Variables
-@section 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:
-
-@table @samp
-@item prefix
-A prefix used in constructing the default values of the variables listed
-below. The default value of @code{prefix} should be @file{/usr/local}
-(at least for now).
-
-@item exec_prefix
-A prefix used in constructing the default values of the some of the
-variables listed below. The default value of @code{exec_prefix} should
-be @code{$(prefix)}.
-
-Generally, @code{$(exec_prefix)} is used for directories that contain
-machine-specific files (such as executables and subroutine libraries),
-while @code{$(prefix)} is used directly for other directories.
-
-@item bindir
-The directory for installing executable programs that users can run.
-This should normally be @file{/usr/local/bin}, but it should be written
-as @file{$(exec_prefix)/bin}.
-
-@item libdir
-The directory for installing executable files to be run by the program
-rather than by users. Object files and libraries of object code should
-also go in this directory. The idea is that this directory is used for
-files that pertain to a specific machine architecture, but need not be
-in the path for commands. The value of @code{libdir} should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(exec_prefix)/lib}.
-
-@item datadir
-The directory for installing read-only data files which the programs
-refer to while they run. This directory is used for files which are
-independent of the type of machine being used. This should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(prefix)/lib}.
-
-@item statedir
-The directory for installing data files which the programs modify while
-they run. These files should be independent of the type of machine
-being used, and it should be possible to share them among machines at a
-network installation. This should normally be @file{/usr/local/lib},
-but it should be written as @file{$(prefix)/lib}.
-
-@item includedir
-The directory for installing @samp{#include} header files to be included
-by user programs. This should normally be @file{/usr/local/include},
-but it should be written as @file{$(prefix)/include}.
-
-Most compilers other than GCC do not look for header files in
-@file{/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
-
-@item oldincludedir
-The directory for installing @samp{#include} header files for use with
-compilers other than GCC. This should normally be @file{/usr/include}.
-
-The Makefile commands should check whether the value of
-@code{oldincludedir} is empty. If it is, they should not try to use
-it; they should cancel the second installation of the header files.
-
-@item mandir
-The directory for installing the man pages (if any) for this package.
-It should include the suffix for the proper section of the
-manual---usually @samp{1} for a utility.
-
-@item man1dir
-The directory for installing section 1 man pages.
-@item man2dir
-The directory for installing section 2 man pages.
-@item @dots{}
-Use these names instead of @samp{mandir} if the package needs to install man
-pages in more than one section of the manual.
-
-@strong{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.}
-
-@item manext
-The file name extension for the installed man page. This should contain
-a period followed by the appropriate digit.
-
-@item infodir
-The directory for installing the info files for this package. By
-default, it should be @file{/usr/local/info}, but it should be written
-as @file{$(prefix)/info}.
-
-@item srcdir
-The directory for the sources being compiled. The value of this
-variable is normally inserted by the @code{configure} shell script.
-@end table
-
-For example:
-
-@example
-# Common prefix for installation directories.
-# NOTE: This directory must exist when you start installation.
-prefix = /usr/local
-exec_prefix = $(prefix)
-# Directory in which to put the executable for the command `gcc'
-bindir = $(exec_prefix)/bin
-# Directory in which to put the directories used by the compiler.
-libdir = $(exec_prefix)/lib
-# Directory in which to put the Info files.
-infodir = $(prefix)/info
-@end example
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
+@include make-stds.texi
@node Configuration
@chapter How Configuration Should Work
as a subroutine to validate system types and canonicalize aliases.
Other options are permitted to specify in more detail the software
-or hardware are present on the machine:
+or hardware present on the machine, and include or exclude optional
+parts of the package:
@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}. This allows users to choose which
+optional features to include. Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another. No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior. The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
The package @var{package} will be installed, so configure this package
to work with @var{package}.
-Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or
-@samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}.
+@c Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include @samp{x}, @samp{x-toolkit},
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and
+@samp{gdb}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files. That is outside the scope of what @samp{--with}
+options are for.
@item --nfp
The target machine has no floating point processor.
@item --gas
The target machine assembler is GAS, the GNU assembler.
-This is obsolete; use @samp{--with-gnu-as} instead.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
@item --x
-The target machine has the X Window system installed.
-This is obsolete; use @samp{--with-x} instead.
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
@end table
All @code{configure} scripts should accept all of these ``detail''
options, whether or not they make any difference to the particular
package at hand. In particular, they should accept any option that
-starts with @samp{--with-}. This is so users will be able to configure
-an entire GNU source tree at once with a single set of options.
+starts with @samp{--with-} or @samp{--enable-}. This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
Packages that perform part of compilation may support cross-compilation.
In such a case, the host and target machines for the program may be
type of target system. The syntax for @var{hosttype} is the same as
described above.
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on. Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
Programs for which cross-operation is not meaningful need not accept the
@samp{--host} option, because configuring an entire operating system for
cross-operation is not a meaningful thing.
identifer comes at the beginning of a sentence, don't capitalize it!
Changing the spelling makes it a different identifier. If you don't
like starting a sentence with a lower case letter, write the sentence
-differently (e.g. ``The identifier lower-case is @dots{}'').
+differently (e.g., ``The identifier lower-case is @dots{}'').
The comment on a function is much clearer if you use the argument
names to speak about the argument values. The variable name itself
should be lower case, but write it in upper case when you are speaking
about the value rather than the variable itself. Thus, ``the inode
-number @var{node_num}'' rather than ``an inode''.
+number NODE_NUM'' rather than ``an inode''.
There is usually no purpose in restating the name of the function in
the comment before it, because the reader can see that for himself.
@example
/* Nonzero means truncate lines in the display;
zero means continue them. */
-
int truncate_lines;
@end example
@chapter Clean Use of C Constructs
Please explicitly declare all arguments to functions.
-Don't omit them just because they are ints.
+Don't omit them just because they are @code{int}s.
-Declarations of external functions and functions to appear later
-in the source file should all go in one place near the beginning of
-the file (somewhere before the first function definition in the file),
-or else should go in a header file. Don't put extern declarations
-inside functions.
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file. Don't put @code{extern} declarations inside
+functions.
+
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
Don't declare multiple variables in one declaration that spans lines.
Start a new declaration on each line, instead. For example, instead
(If they are global variables, each should have a comment preceding it
anyway.)
-When you have an if-else statement nested in another if statement,
-always put braces around the if-else. Thus, never write like this:
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
@example
if (foo)
@}
@end example
-If you have an if statement nested inside of an else statement,
-either write @code{else if} on one line, like this,
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
@example
if (foo)
@end example
@noindent
-with its then-part indented like the preceding then-part, or write the
-nested if within braces like this:
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
@example
if (foo)
same declaration. Instead, declare the structure tag separately
and then use it to declare the variables or typedefs.
-Try to avoid assignments inside if-conditions. For example, don't
-write this:
+Try to avoid assignments inside @code{if}-conditions. For example,
+don't write this:
@example
if ((foo = (char *) malloc (sizeof *foo)) == 0)
fatal ("virtual memory exhausted");
@end example
-Don't make the program ugly to placate lint. Please don't insert any
-casts to void. Zero without a cast is perfectly fine as a null
+Don't make the program ugly to placate @code{lint}. Please don't insert any
+casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant.
-
@node Names
@chapter Naming Variables and Functions
Please use underscores to separate words in a name, so that the Emacs
word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and enum constants, and for name-prefixes that
-follow a uniform convention.
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
For example, you should use names like @code{ignore_space_change_flag};
don't use names like @code{iCantReadThis}.
constants.
Use file names of 14 characters or less, to avoid creating gratuitous
-problems on System V.
+problems on System V. You can use the program @code{doschk} to test for
+this. @code{doschk} also tests for potential name conflicts if the
+files were loaded onto an MS-DOS file system---something you may or may
+not care about.
@node Using Extensions
On the one hand, using the extensions can make a cleaner program.
On the other hand, people will not be able to build the program
-unless the other GNU tools are available. This might cause the
+unless the other GNU tools are available. This might cause the
program to work on fewer kinds of machines.
With some extensions, it might be easy to provide both alternatives.
same considerations apply. (Except for @sc{ANSI} features that we
discourage, such as trigraphs---don't ever use them.)
+
+@node System Functions
+@chapter Calling System Functions
+
+C implementations differ substantially. ANSI C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-ANSI compilers. This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the value of @code{sprintf}. It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions. If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens. The problem is only theoretical. By
+contrast, actual declarations have frequently caused actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not an ANSI prototype. The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}. These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine. For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@item
+The string functions require special treatment. Some Unix systems have
+a header file @file{string.h}; other have @file{strings.h}. Neither
+file name is portable. There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think. The newer ANSI
+string functions are off-limits anyway because many systems still don't
+support them. The string functions you can use are these:
+
+@example
+strcpy strncpy strcat strncat
+strlen strcmp strncmp
+strchr strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values. Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases. It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}. Luckily,
+there is no variation in the data type they return. But there is
+variation in their names. Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}. Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program. (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr}.) Declare both of those names as functions returning
+@code{char *}. On systems which don't support those names, define them
+as macros in terms of the other pair. For example, here is what to put
+at the beginning of your file (or in a header) if you want to use the
+names @code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
@node Semantics
-@chapter Program Behaviour for All Programs
+@chapter Program Behavior for All Programs
Avoid arbitrary limits on the length or number of @emph{any} data
structure, including filenames, lines, files, and symbols, by allocating
freed. Anything you want to fetch from the block, you must fetch before
calling @code{free}.
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.
+
Use @code{getopt_long} to decode arguments, unless the argument syntax
makes this unreasonable.
@node Libraries
-@chapter Library Behaviour
+@chapter Library Behavior
Try to make library functions reentrant. If they need to do dynamic
storage allocation, at least try to avoid any nonreentrancy aside from
External symbols that are not documented entry points for the user
should have names beginning with @samp{_}. They should also contain
the chosen name prefix for the library, to prevent collisions with
-other libraries. These can go in the same files with user entry
+other libraries. These can go in the same files with user entry
points if you like.
Static functions and variables can be used as you like and need not
@chapter Portability As It Applies to GNU
Much of what is called ``portability'' in the Unix world refers to
-porting to different Unix versions. This is not relevant to GNU
-software, because its purpose is to run on top of one and only
-one kernel, the GNU kernel, compiled with one and only one C
-compiler, the GNU C compiler. The amount and kinds of variation
-among GNU systems on different cpu's will be like the variation
-among Berkeley 4.3 systems on different cpu's.
+porting to different Unix versions. This is a secondary consideration
+for GNU software, because its primary purpose is to run on top of one
+and only one kernel, the GNU kernel, compiled with one and only one C
+compiler, the GNU C compiler. The amount and kinds of variation among
+GNU systems on different cpu's will be like the variation among Berkeley
+4.3 systems on different cpu's.
+
+All users today run GNU software on non-GNU systems. So supporting a
+variety of non-GNU systems is desirable; simply not paramount.
+The easiest way to achieve portability to a reasonable range of systems
+is to use Autoconf. It's unlikely that your program needs to know more
+information about the host machine than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
It is difficult to be sure exactly what facilities the GNU kernel
will provide, since it isn't finished yet. Therefore, assume you can
use anything in 4.3; just avoid using the format of semi-internal data
bases (e.g., directories) when there is a higher-level alternative
-(readdir).
+(@code{readdir}).
You can freely assume any reasonably standard facilities in the C
language, libraries or kernel, because we will find it necessary to
probably make your program work even on weird machines.
Since some important machines (including the 68000) are big-endian,
-it is important not to assume that the address of an int object
+it is important not to assume that the address of an @code{int} object
is also the address of its least-significant byte. Thus, don't
make the following mistake:
Instead, use a run time option or a compilation switch or both
to select among the alternate behaviors.
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it
+merely to save someone from typing an option now and then.
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device. It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
It is a good idea to follow the @sc{POSIX} guidelines for the
command-line options of a program. The easiest way to do this is to use
@code{getopt} to parse them. Note that the GNU version of @code{getopt}
friendly this way. This is easy to do with the GNU function
@code{getopt_long}.
+One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}. To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program. The table appears below.
+
+If you use names not already in the table, please send
+@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we
+can update the table.
+
It is usually a good idea for file names given as ordinary arguments
to be input files only; any output files would be specified using
options (preferably @samp{-o}). Even if you allow an output file name
remember.
Programs should support an option @samp{--version} which prints the
-program's version number, and an option @samp{--help} which prints
-option usage information.
+program's version number on standard output and exits successfully, and
+an option @samp{--help} which prints option usage information on
+standard output and exits successfully. These options should inhibit
+the normal function of the command; they should do nothing except print
+the requested information.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period. --friedman
+
+@table @samp
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item archive-name
+@samp{-n} in @code{shar}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item backward-search
+@samp{-B} in etags.
+
+@item basename
+@samp{-f} in @code{shar}.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item bits-per-code
+@samp{-b} in @code{shar}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c@t{++}
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyright
+@samp{-C} in @code{ptx} and @code{recode}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cut-mark
+@samp{-c} in @code{shar}.
+
+@item cxref
+@samp{-x} in @code{etags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{etags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs. In @code{ls}, it
+means to show directories themselves rather than their contents. In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item diversions
+@samp{-N} in @code{m4}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in Makeinfo.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item exit-0
+@samp{-e} in @code{unshar}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+
+@item file
+@samp{-f} in @code{info}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in Makeinfo.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in Makeinfo.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item force-prefix
+@samp{-F} in @code{shar}.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item forward-search
+@samp{-F} in @code{etags}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item here-delimiter
+@samp{-d} in @code{shar}.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+@item ignore-indentation
+@samp{-S} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do and tell @code{gnu@@prep.ai.mit.edu}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-piping
+@samp{-P} in @code{shar}.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in Makeinfo.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-timestamp
+@samp{-m} in @code{shar}.
+
+@item no-validate
+Used in Makeinfo.
+
+@item no-verbose
+@samp{-v} in @code{shar}.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item output
+In various programs, specify the output file name.
+
+@item output-prefix
+@samp{-o} in @code{shar}.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item overwrite
+@samp{-c} in @code{unshar}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in Makeinfo.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item query-user
+@samp{-X} in @code{shar}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output. @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in Makeinfo.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item sort
+Used in @code{ls}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item split-at
+@samp{-E} in @code{unshar}.
+
+@item split-size-limit
+@samp{-L} in @code{shar}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item submitter
+@samp{-s} in @code{shar}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item text-files
+@samp{-T} in @code{shar}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-G} in @code{m4} and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{etags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{etags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @samp{etags}, @samp{mv}, @samp{tar}.
+
+@item uuencode
+@samp{-B} in @code{shar}.
+
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+
+@item verbose
+Print more information about progress. Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{etags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+
+@end table
@node Documentation
@chapter Documenting Programs
Please use Texinfo for documenting GNU programs. See the Texinfo
manual, either the hardcopy or the version in the GNU Emacs Info
-sub-system (@kbd{C-h i}).
-
-See existing GNU texinfo files (e.g. those under the @file{man/}
-directory in the GNU Emacs Distribution) for examples.
+subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g., those
+under the @file{man/} directory in the GNU Emacs distribution) for
+examples.
The title page of the manual should state the version of the program
which the manual applies to. The Top node of the manual should also
the manual as a list of features. Instead, organize it by the
concepts a user will have before reaching that point in the manual.
Address the goals that a user will have in mind, and explain how to
-accomplish them.
-
+accomplish them. Don't use Unix man pages as a model for how to
+write GNU documentation; they are a bad example to follow.
+
+The manual should have a node named @samp{@var{program} Invocation} or
+@samp{Invoking @var{program}}, where @var{program} stands for the name
+of the program being described, as you would type it in the shell to run
+the program. This node (together with its subnodes, if any) should
+describe the program's command line arguments and how to run it (the
+sort of information people would look in a man page for). Start with an
+@samp{@@example} containing a template for all the options and arguments
+that the program uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns. This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+If one manual describes several programs, it should have such a node for
+each program described.
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file and
+identify the version they pertain to. Don't discard old items; leave
+them in the file after the newer items. This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead. We use the term
+``path'' only for search paths, which are lists of file names.
+
+It is ok to supply a man page for the program as well as a Texinfo
+manual if you wish to. But keep in mind that supporting a man page
+requires continual effort, each time the program is changed. Any time
+you spend on the man page is time taken away from more useful things you
+could contribute.
+
+Thus, even if a user volunteers to donate a man page, you may find this
+gift costly to accept. Unless you have time on your hands, it may be
+better to refuse the man page unless the same volunteer agrees to take
+full responsibility for maintaining it---so that you can wash your hands
+of it entirely. If the volunteer ceases to do the job, then don't feel
+obliged to pick it up yourself; it may be better to withdraw the man
+page until another volunteer offers to carry on with it.
+
+Alternatively, if you expect the discrepancies to be small enough that
+the man page remains useful, put a prominent note near the beginning of
+the man page explaining that you don't maintain it and that the Texinfo
+manual is more authoritative, and describing how to access the Texinfo
+documentation.
@node Releases
@chapter Making Releases
-Package the distribution of Foo version 69.96 in a tar file named
-@file{foo-69.96.tar}. It should unpack into a subdirectory named
-@file{foo-69.96}.
+Package the distribution of Foo version 69.96 in a gzipped tar file
+named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory
+named @file{foo-69.96}.
Building and installing the program should never modify any of the files
contained in the distribution. This means that all the files that form
Naturally, all the source files must be in the distribution. It is okay
to include non-source files in the distribution, provided they are
up-to-date and machine-independent, so that building the distribution
-normally will never modify them. We commonly included non-source files
+normally will never modify them. We commonly include non-source files
produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid
unnecessary dependencies between our distributions, so that users can
install whichever packages they want to install.
distribution. So if you do distribute non-source files, always make
sure they are up to date when you make a new distribution.
-Make sure that no file name in the distribution is no more than 14
-characters long. Nowadays, there are systems that adhere to a foolish
-interpretation of the POSIX standard which holds that they should refuse
-to open a longer name, rather than truncating as they did in the past.
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+Don't include any symbolic links in the distribution itself. If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
Try to make sure that all the file names will be unique on MS-DOG. A
name on MS-DOG consists of up to 8 characters, optionally followed by a
period and up to three characters. MS-DOG will truncate extra
characters both before and after the period. Thus,
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
-are truncated to @file{foobarhac.c} and @file{foobarhac.o}, which are
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
distinct.
Include in your distribution a copy of the @file{texinfo.tex} you used
Leaving them out would make the distribution file a little smaller at
the expense of possible inconvenience to a user who doesn't know what
other files to get.
+
+@contents
+
@bye
\input texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename standards.text
+@setfilename standards.info
@settitle GNU Coding Standards
+@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
+@set lastupdate 21 September 1994
@c %**end of header
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
@setchapternewpage off
@ifinfo
-Copyright (C) 1992 Free Software Foundation
+GNU Coding Standards
+Copyright (C) 1992, 1993, 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.
@end ifinfo
@titlepage
-@sp 10
-@titlefont{GNU Coding Standards}
-@author{Richard Stallman}
-@author{last updated 16 May 1992}
-@c Note date also appears below.
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992 Free Software Foundation
+Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
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 Free Software Foundation.
+by the Free Software Foundation.
@end titlepage
@ifinfo
-@node Top, Reading Non-Free Code, (dir), (dir)
+@node Top, Preface, (dir), (dir)
@top Version
-Last updated 16 May 1992.
-@c Note date also appears above.
+Last updated @value{lastupdate}.
@end ifinfo
@menu
+* Preface:: About the GNU Coding Standards
* Reading Non-Free Code:: Referring to Proprietary Programs
* Contributions:: Accepting Contributions
* Change Logs:: Recording Changes
-* Compatibility:: Compatibility with Other Implementations
-* Makefiles:: Makefile Conventions
+* Compatibility:: Compatibility with Other Implementations
+* Makefile Conventions:: Makefile Conventions
* Configuration:: How Configuration Should Work
* Source Language:: Using Languages Other Than C
* Formatting:: Formatting Your Source Code
* Syntactic Conventions:: Clean Use of C Constructs
* Names:: Naming Variables and Functions
* Using Extensions:: Using Non-standard Features
-* Semantics:: Program Behaviour for All Programs
+* System Functions:: Portability and ``standard'' library functions
+* Semantics:: Program Behavior for All Programs
* Errors:: Formatting Error Messages
-* Libraries:: Library Behaviour
+* Libraries:: Library Behavior
* Portability:: Portability As It Applies to GNU
* User Interfaces:: Standards for Command Line Interfaces
* Documentation:: Documenting Programs
* Releases:: Making Releases
@end menu
+@node Preface
+@chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to write portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+Corrections or suggestions regarding this document should be sent to
+@code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
@node Reading Non-Free Code
@chapter Referring to Proprietary Programs
* stmt.c (assign_parms): Round size up for move_block_from_reg.
@end example
-There's no need to describe here the full purpose of the changes or how
-they work together. It is better to put this explanation in comments in
-the code. That's why just ``New function'' is enough; there is a
-comment with the function in the source to explain what it does.
+It's important to name the changed function or variable in full. Don't
+abbreviate them; don't combine them. Subsequent maintainers will often
+search for a function name to find all the change log entries that
+pertain to it; if you abbreviate the name, they won't find it when they
+search. For example, some people are tempted to abbreviate groups of
+function names by writing @samp{* register.el
+(@{insert,jump-to@}-register)}; this is not a good idea, since searching
+for @code{jump-to-register} or @code{insert-register} would not find the
+entry.
+
+There's no need to describe the full purpose of the changes or how they
+work together. It is better to put such explanations in comments in the
+code. That's why just ``New function'' is enough; there is a comment
+with the function in the source to explain what it does.
However, sometimes it is useful to write one line to describe the
overall purpose of a large batch of changes.
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it. What they want from a change log is a
+clear explanation of how the earlier version differed.
+
When you change the calling sequence of a function in a simple
fashion, and you change all the callers of the function, there is no
need to make individual entries for all the callers. Just write in
@node Compatibility
-@chapter Compatibility with Other Implementations
+@chapter Compatibility with Other Implementations
With certain exceptions, utility programs and libraries for GNU should
be upward compatible with those in Berkeley Unix, and upward compatible
then it is not really upward compatible. Try to redesign its
interface.
+Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
When a feature is used only by users (not by programs or command
files), and it is done poorly in Unix, feel free to replace it
completely with something totally different and better. (For example,
but our first priority is usually to duplicate what Unix already
has.
-
-@node Makefiles
-@chapter Makefile Conventions
-
-This chapter describes conventions for writing Makefiles.
-
-@menu
-* Makefile Basics::
-* Standard Targets::
-* Command Variables::
-* Directory Variables::
-@end menu
-
-@node Makefile Basics
-@section General Conventions for Makefiles
-
-Every Makefile should contain this line:
-
-@example
-SHELL = /bin/sh
-@end example
-
-@noindent
-to avoid trouble on systems where the @code{SHELL} variable might be
-inherited from the environment.
-
-Don't assume that @file{.} is in the path for command execution. When
-you need to run programs that are files in the current directory, always
-use @file{./} to make sure the proper file is run regardless of the
-current path.
-
-@node Standard Targets
-@section Standard Targets for Users
-
-All GNU programs should have the following targets in their Makefiles:
-
-@table @samp
-@item all
-Compile the entire program.
-
-@item 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 then run that
-test.
-
-Use @samp{-} before any command for installing a man page, so that
-@code{make} will ignore any errors. This is in case there are systems
-that don't have the Unix man page documentation system installed.
-
-@item 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 @file{.dvi} files here if they are not part of the distribution.
-
-@item 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, @samp{make
-distclean} should leave only the files that were in the distribution.
-
-@item mostlyclean
-Like @samp{clean}, but may refrain from deleting a few files that people
-normally don't want to recompile. For example, the @samp{mostlyclean}
-target for GCC does not delete @file{libgcc.a}, because recompiling it
-is rarely necessary and takes a lot of time.
-
-@item realclean
-Delete 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.
-
-@item TAGS
-Update a tags table for this program.
-
-@item 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 @file{gcc-1.40}.
-
-The easiest way to do this is to create a subdirectory appropriately
-named, use @code{ln} or @code{cp} to install the proper files in it, and
-then @code{tar} that subdirectory.
-
-The @code{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. @xref{Releases}.
-
-@item 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.
-@end table
-
-@node Command Variables
-@section 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 @code{BISON} whose default
-value is set with @samp{BISON = bison}, and refer to it with
-@code{$(BISON)} whenever you need to use Bison.
-
-Each program-name variable should come with an options variable that is
-used to supply options to the program. Append @samp{FLAGS} to the
-program-name variable name to get the options variable name---for
-example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
-this rule, but we keep it because it is standard.)
-
-File-management utilities such as @code{ln}, @code{rm}, @code{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.
-
-Every Makefile should define the variable @code{INSTALL}, which is the
-basic command for installing a file into the system.
-
-Every Makefile should also define variables @code{INSTALL_PROGRAM} and
-@code{INSTALL_DATA}. (The default for each of these should be
-@code{$(INSTALL)}.) Then it should use those variables as the commands
-for actual installation, for executables and nonexecutables
-respectively. Use these variables as follows:
-
-@example
-$(INSTALL_PROGRAM) foo $@{bindir@}/foo
-$(INSTALL_DATA) libfoo.a $@{libdir@}/libfoo.a
-@end example
-
-@noindent
-(Always use a file name, not a directory name, as the second argument.
-Use a separate command for each file to be installed.)
-
-@node Directory Variables
-@section 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:
-
-@table @samp
-@item prefix
-A prefix used in constructing the default values of the variables listed
-below. The default value of @code{prefix} should be @file{/usr/local}
-(at least for now).
-
-@item exec_prefix
-A prefix used in constructing the default values of the some of the
-variables listed below. The default value of @code{exec_prefix} should
-be @code{$(prefix)}.
-
-Generally, @code{$(exec_prefix)} is used for directories that contain
-machine-specific files (such as executables and subroutine libraries),
-while @code{$(prefix)} is used directly for other directories.
-
-@item bindir
-The directory for installing executable programs that users can run.
-This should normally be @file{/usr/local/bin}, but it should be written
-as @file{$(exec_prefix)/bin}.
-
-@item libdir
-The directory for installing executable files to be run by the program
-rather than by users. Object files and libraries of object code should
-also go in this directory. The idea is that this directory is used for
-files that pertain to a specific machine architecture, but need not be
-in the path for commands. The value of @code{libdir} should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(exec_prefix)/lib}.
-
-@item datadir
-The directory for installing read-only data files which the programs
-refer to while they run. This directory is used for files which are
-independent of the type of machine being used. This should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(prefix)/lib}.
-
-@item statedir
-The directory for installing data files which the programs modify while
-they run. These files should be independent of the type of machine
-being used, and it should be possible to share them among machines at a
-network installation. This should normally be @file{/usr/local/lib},
-but it should be written as @file{$(prefix)/lib}.
-
-@item includedir
-The directory for installing @samp{#include} header files to be included
-by user programs. This should normally be @file{/usr/local/include},
-but it should be written as @file{$(prefix)/include}.
-
-Most compilers other than GCC do not look for header files in
-@file{/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
-
-@item oldincludedir
-The directory for installing @samp{#include} header files for use with
-compilers other than GCC. This should normally be @file{/usr/include}.
-
-The Makefile commands should check whether the value of
-@code{oldincludedir} is empty. If it is, they should not try to use
-it; they should cancel the second installation of the header files.
-
-@item mandir
-The directory for installing the man pages (if any) for this package.
-It should include the suffix for the proper section of the
-manual---usually @samp{1} for a utility.
-
-@item man1dir
-The directory for installing section 1 man pages.
-@item man2dir
-The directory for installing section 2 man pages.
-@item @dots{}
-Use these names instead of @samp{mandir} if the package needs to install man
-pages in more than one section of the manual.
-
-@strong{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.}
-
-@item manext
-The file name extension for the installed man page. This should contain
-a period followed by the appropriate digit.
-
-@item infodir
-The directory for installing the info files for this package. By
-default, it should be @file{/usr/local/info}, but it should be written
-as @file{$(prefix)/info}.
-
-@item srcdir
-The directory for the sources being compiled. The value of this
-variable is normally inserted by the @code{configure} shell script.
-@end table
-
-For example:
-
-@example
-# Common prefix for installation directories.
-# NOTE: This directory must exist when you start installation.
-prefix = /usr/local
-exec_prefix = $(prefix)
-# Directory in which to put the executable for the command `gcc'
-bindir = $(exec_prefix)/bin
-# Directory in which to put the directories used by the compiler.
-libdir = $(exec_prefix)/lib
-# Directory in which to put the Info files.
-infodir = $(prefix)/info
-@end example
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
+@include make-stds.texi
@node Configuration
@chapter How Configuration Should Work
as a subroutine to validate system types and canonicalize aliases.
Other options are permitted to specify in more detail the software
-or hardware are present on the machine:
+or hardware present on the machine, and include or exclude optional
+parts of the package:
@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}. This allows users to choose which
+optional features to include. Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another. No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior. The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
The package @var{package} will be installed, so configure this package
to work with @var{package}.
-Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or
-@samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}.
+@c Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include @samp{x}, @samp{x-toolkit},
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and
+@samp{gdb}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files. That is outside the scope of what @samp{--with}
+options are for.
@item --nfp
The target machine has no floating point processor.
@item --gas
The target machine assembler is GAS, the GNU assembler.
-This is obsolete; use @samp{--with-gnu-as} instead.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
@item --x
-The target machine has the X Window system installed.
-This is obsolete; use @samp{--with-x} instead.
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
@end table
All @code{configure} scripts should accept all of these ``detail''
options, whether or not they make any difference to the particular
package at hand. In particular, they should accept any option that
-starts with @samp{--with-}. This is so users will be able to configure
-an entire GNU source tree at once with a single set of options.
+starts with @samp{--with-} or @samp{--enable-}. This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
Packages that perform part of compilation may support cross-compilation.
In such a case, the host and target machines for the program may be
type of target system. The syntax for @var{hosttype} is the same as
described above.
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on. Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
Programs for which cross-operation is not meaningful need not accept the
@samp{--host} option, because configuring an entire operating system for
cross-operation is not a meaningful thing.
identifer comes at the beginning of a sentence, don't capitalize it!
Changing the spelling makes it a different identifier. If you don't
like starting a sentence with a lower case letter, write the sentence
-differently (e.g. ``The identifier lower-case is @dots{}'').
+differently (e.g., ``The identifier lower-case is @dots{}'').
The comment on a function is much clearer if you use the argument
names to speak about the argument values. The variable name itself
should be lower case, but write it in upper case when you are speaking
about the value rather than the variable itself. Thus, ``the inode
-number @var{node_num}'' rather than ``an inode''.
+number NODE_NUM'' rather than ``an inode''.
There is usually no purpose in restating the name of the function in
the comment before it, because the reader can see that for himself.
@example
/* Nonzero means truncate lines in the display;
zero means continue them. */
-
int truncate_lines;
@end example
@chapter Clean Use of C Constructs
Please explicitly declare all arguments to functions.
-Don't omit them just because they are ints.
+Don't omit them just because they are @code{int}s.
-Declarations of external functions and functions to appear later
-in the source file should all go in one place near the beginning of
-the file (somewhere before the first function definition in the file),
-or else should go in a header file. Don't put extern declarations
-inside functions.
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file. Don't put @code{extern} declarations inside
+functions.
+
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
Don't declare multiple variables in one declaration that spans lines.
Start a new declaration on each line, instead. For example, instead
(If they are global variables, each should have a comment preceding it
anyway.)
-When you have an if-else statement nested in another if statement,
-always put braces around the if-else. Thus, never write like this:
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
@example
if (foo)
@}
@end example
-If you have an if statement nested inside of an else statement,
-either write @code{else if} on one line, like this,
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
@example
if (foo)
@end example
@noindent
-with its then-part indented like the preceding then-part, or write the
-nested if within braces like this:
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
@example
if (foo)
same declaration. Instead, declare the structure tag separately
and then use it to declare the variables or typedefs.
-Try to avoid assignments inside if-conditions. For example, don't
-write this:
+Try to avoid assignments inside @code{if}-conditions. For example,
+don't write this:
@example
if ((foo = (char *) malloc (sizeof *foo)) == 0)
fatal ("virtual memory exhausted");
@end example
-Don't make the program ugly to placate lint. Please don't insert any
-casts to void. Zero without a cast is perfectly fine as a null
+Don't make the program ugly to placate @code{lint}. Please don't insert any
+casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant.
-
@node Names
@chapter Naming Variables and Functions
Please use underscores to separate words in a name, so that the Emacs
word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and enum constants, and for name-prefixes that
-follow a uniform convention.
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
For example, you should use names like @code{ignore_space_change_flag};
don't use names like @code{iCantReadThis}.
constants.
Use file names of 14 characters or less, to avoid creating gratuitous
-problems on System V.
+problems on System V. You can use the program @code{doschk} to test for
+this. @code{doschk} also tests for potential name conflicts if the
+files were loaded onto an MS-DOS file system---something you may or may
+not care about.
@node Using Extensions
On the one hand, using the extensions can make a cleaner program.
On the other hand, people will not be able to build the program
-unless the other GNU tools are available. This might cause the
+unless the other GNU tools are available. This might cause the
program to work on fewer kinds of machines.
With some extensions, it might be easy to provide both alternatives.
same considerations apply. (Except for @sc{ANSI} features that we
discourage, such as trigraphs---don't ever use them.)
+
+@node System Functions
+@chapter Calling System Functions
+
+C implementations differ substantially. ANSI C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-ANSI compilers. This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the value of @code{sprintf}. It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions. If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens. The problem is only theoretical. By
+contrast, actual declarations have frequently caused actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not an ANSI prototype. The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}. These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine. For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@item
+The string functions require special treatment. Some Unix systems have
+a header file @file{string.h}; other have @file{strings.h}. Neither
+file name is portable. There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think. The newer ANSI
+string functions are off-limits anyway because many systems still don't
+support them. The string functions you can use are these:
+
+@example
+strcpy strncpy strcat strncat
+strlen strcmp strncmp
+strchr strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values. Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases. It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}. Luckily,
+there is no variation in the data type they return. But there is
+variation in their names. Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}. Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program. (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr}.) Declare both of those names as functions returning
+@code{char *}. On systems which don't support those names, define them
+as macros in terms of the other pair. For example, here is what to put
+at the beginning of your file (or in a header) if you want to use the
+names @code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
@node Semantics
-@chapter Program Behaviour for All Programs
+@chapter Program Behavior for All Programs
Avoid arbitrary limits on the length or number of @emph{any} data
structure, including filenames, lines, files, and symbols, by allocating
freed. Anything you want to fetch from the block, you must fetch before
calling @code{free}.
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.
+
Use @code{getopt_long} to decode arguments, unless the argument syntax
makes this unreasonable.
@node Libraries
-@chapter Library Behaviour
+@chapter Library Behavior
Try to make library functions reentrant. If they need to do dynamic
storage allocation, at least try to avoid any nonreentrancy aside from
External symbols that are not documented entry points for the user
should have names beginning with @samp{_}. They should also contain
the chosen name prefix for the library, to prevent collisions with
-other libraries. These can go in the same files with user entry
+other libraries. These can go in the same files with user entry
points if you like.
Static functions and variables can be used as you like and need not
@chapter Portability As It Applies to GNU
Much of what is called ``portability'' in the Unix world refers to
-porting to different Unix versions. This is not relevant to GNU
-software, because its purpose is to run on top of one and only
-one kernel, the GNU kernel, compiled with one and only one C
-compiler, the GNU C compiler. The amount and kinds of variation
-among GNU systems on different cpu's will be like the variation
-among Berkeley 4.3 systems on different cpu's.
+porting to different Unix versions. This is a secondary consideration
+for GNU software, because its primary purpose is to run on top of one
+and only one kernel, the GNU kernel, compiled with one and only one C
+compiler, the GNU C compiler. The amount and kinds of variation among
+GNU systems on different cpu's will be like the variation among Berkeley
+4.3 systems on different cpu's.
+
+All users today run GNU software on non-GNU systems. So supporting a
+variety of non-GNU systems is desirable; simply not paramount.
+The easiest way to achieve portability to a reasonable range of systems
+is to use Autoconf. It's unlikely that your program needs to know more
+information about the host machine than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
It is difficult to be sure exactly what facilities the GNU kernel
will provide, since it isn't finished yet. Therefore, assume you can
use anything in 4.3; just avoid using the format of semi-internal data
bases (e.g., directories) when there is a higher-level alternative
-(readdir).
+(@code{readdir}).
You can freely assume any reasonably standard facilities in the C
language, libraries or kernel, because we will find it necessary to
probably make your program work even on weird machines.
Since some important machines (including the 68000) are big-endian,
-it is important not to assume that the address of an int object
+it is important not to assume that the address of an @code{int} object
is also the address of its least-significant byte. Thus, don't
make the following mistake:
Instead, use a run time option or a compilation switch or both
to select among the alternate behaviors.
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it
+merely to save someone from typing an option now and then.
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device. It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
It is a good idea to follow the @sc{POSIX} guidelines for the
command-line options of a program. The easiest way to do this is to use
@code{getopt} to parse them. Note that the GNU version of @code{getopt}
friendly this way. This is easy to do with the GNU function
@code{getopt_long}.
+One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}. To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program. The table appears below.
+
+If you use names not already in the table, please send
+@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we
+can update the table.
+
It is usually a good idea for file names given as ordinary arguments
to be input files only; any output files would be specified using
options (preferably @samp{-o}). Even if you allow an output file name
remember.
Programs should support an option @samp{--version} which prints the
-program's version number, and an option @samp{--help} which prints
-option usage information.
+program's version number on standard output and exits successfully, and
+an option @samp{--help} which prints option usage information on
+standard output and exits successfully. These options should inhibit
+the normal function of the command; they should do nothing except print
+the requested information.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period. --friedman
+
+@table @samp
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item archive-name
+@samp{-n} in @code{shar}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item backward-search
+@samp{-B} in etags.
+
+@item basename
+@samp{-f} in @code{shar}.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item bits-per-code
+@samp{-b} in @code{shar}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c@t{++}
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyright
+@samp{-C} in @code{ptx} and @code{recode}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cut-mark
+@samp{-c} in @code{shar}.
+
+@item cxref
+@samp{-x} in @code{etags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{etags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs. In @code{ls}, it
+means to show directories themselves rather than their contents. In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item diversions
+@samp{-N} in @code{m4}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in Makeinfo.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item exit-0
+@samp{-e} in @code{unshar}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+
+@item file
+@samp{-f} in @code{info}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in Makeinfo.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in Makeinfo.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item force-prefix
+@samp{-F} in @code{shar}.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item forward-search
+@samp{-F} in @code{etags}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item here-delimiter
+@samp{-d} in @code{shar}.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+@item ignore-indentation
+@samp{-S} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do and tell @code{gnu@@prep.ai.mit.edu}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-piping
+@samp{-P} in @code{shar}.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in Makeinfo.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-timestamp
+@samp{-m} in @code{shar}.
+
+@item no-validate
+Used in Makeinfo.
+
+@item no-verbose
+@samp{-v} in @code{shar}.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item output
+In various programs, specify the output file name.
+
+@item output-prefix
+@samp{-o} in @code{shar}.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item overwrite
+@samp{-c} in @code{unshar}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in Makeinfo.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item query-user
+@samp{-X} in @code{shar}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output. @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in Makeinfo.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item sort
+Used in @code{ls}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item split-at
+@samp{-E} in @code{unshar}.
+
+@item split-size-limit
+@samp{-L} in @code{shar}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item submitter
+@samp{-s} in @code{shar}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item text-files
+@samp{-T} in @code{shar}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-G} in @code{m4} and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{etags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{etags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @samp{etags}, @samp{mv}, @samp{tar}.
+
+@item uuencode
+@samp{-B} in @code{shar}.
+
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+
+@item verbose
+Print more information about progress. Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{etags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+
+@end table
@node Documentation
@chapter Documenting Programs
Please use Texinfo for documenting GNU programs. See the Texinfo
manual, either the hardcopy or the version in the GNU Emacs Info
-sub-system (@kbd{C-h i}).
-
-See existing GNU texinfo files (e.g. those under the @file{man/}
-directory in the GNU Emacs Distribution) for examples.
+subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g., those
+under the @file{man/} directory in the GNU Emacs distribution) for
+examples.
The title page of the manual should state the version of the program
which the manual applies to. The Top node of the manual should also
the manual as a list of features. Instead, organize it by the
concepts a user will have before reaching that point in the manual.
Address the goals that a user will have in mind, and explain how to
-accomplish them.
-
+accomplish them. Don't use Unix man pages as a model for how to
+write GNU documentation; they are a bad example to follow.
+
+The manual should have a node named @samp{@var{program} Invocation} or
+@samp{Invoking @var{program}}, where @var{program} stands for the name
+of the program being described, as you would type it in the shell to run
+the program. This node (together with its subnodes, if any) should
+describe the program's command line arguments and how to run it (the
+sort of information people would look in a man page for). Start with an
+@samp{@@example} containing a template for all the options and arguments
+that the program uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns. This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+If one manual describes several programs, it should have such a node for
+each program described.
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file and
+identify the version they pertain to. Don't discard old items; leave
+them in the file after the newer items. This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead. We use the term
+``path'' only for search paths, which are lists of file names.
+
+It is ok to supply a man page for the program as well as a Texinfo
+manual if you wish to. But keep in mind that supporting a man page
+requires continual effort, each time the program is changed. Any time
+you spend on the man page is time taken away from more useful things you
+could contribute.
+
+Thus, even if a user volunteers to donate a man page, you may find this
+gift costly to accept. Unless you have time on your hands, it may be
+better to refuse the man page unless the same volunteer agrees to take
+full responsibility for maintaining it---so that you can wash your hands
+of it entirely. If the volunteer ceases to do the job, then don't feel
+obliged to pick it up yourself; it may be better to withdraw the man
+page until another volunteer offers to carry on with it.
+
+Alternatively, if you expect the discrepancies to be small enough that
+the man page remains useful, put a prominent note near the beginning of
+the man page explaining that you don't maintain it and that the Texinfo
+manual is more authoritative, and describing how to access the Texinfo
+documentation.
@node Releases
@chapter Making Releases
-Package the distribution of Foo version 69.96 in a tar file named
-@file{foo-69.96.tar}. It should unpack into a subdirectory named
-@file{foo-69.96}.
+Package the distribution of Foo version 69.96 in a gzipped tar file
+named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory
+named @file{foo-69.96}.
Building and installing the program should never modify any of the files
contained in the distribution. This means that all the files that form
Naturally, all the source files must be in the distribution. It is okay
to include non-source files in the distribution, provided they are
up-to-date and machine-independent, so that building the distribution
-normally will never modify them. We commonly included non-source files
+normally will never modify them. We commonly include non-source files
produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid
unnecessary dependencies between our distributions, so that users can
install whichever packages they want to install.
distribution. So if you do distribute non-source files, always make
sure they are up to date when you make a new distribution.
-Make sure that no file name in the distribution is no more than 14
-characters long. Nowadays, there are systems that adhere to a foolish
-interpretation of the POSIX standard which holds that they should refuse
-to open a longer name, rather than truncating as they did in the past.
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+Don't include any symbolic links in the distribution itself. If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
Try to make sure that all the file names will be unique on MS-DOG. A
name on MS-DOG consists of up to 8 characters, optionally followed by a
period and up to three characters. MS-DOG will truncate extra
characters both before and after the period. Thus,
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
-are truncated to @file{foobarhac.c} and @file{foobarhac.o}, which are
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
distinct.
Include in your distribution a copy of the @file{texinfo.tex} you used
Leaving them out would make the distribution file a little smaller at
the expense of possible inconvenience to a user who doesn't know what
other files to get.
+
+@contents
+
@bye
projects / thirdparty / autoconf.git / commitdiff
