source: trunk/essentials/sys-devel/autoconf-2.13/standards.info@ 3159

This is Info file standards.info, produced by Makeinfo version 1.67
from the input file /home/bje/autoconf-2.13/standards.texi.

START-INFO-DIR-ENTRY
* Standards: (standards).        GNU coding standards.
END-INFO-DIR-ENTRY

   GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
1997, 1998 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)

Version
*******

   Last updated August 26, 1998.

* Menu:

* Preface::                     About the GNU Coding Standards
* Intellectual Property::       Keeping Free Software Free
* Design Advice::               General Program Design
* Program Behavior::            Program Behavior for All Programs
* Writing C::                   Making The Best Use of C
* Documentation::               Documenting Programs
* Managing Releases::           The Release Process


File: standards.info,  Node: Preface,  Next: Intellectual Property,  Prev: Top,  Up: Top

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 writing 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 for this document should be sent to
<[email protected]>.  If you make a suggestion, please include a suggested
new wording for it; our time is limited.  We prefer a context diff to
the `standards.texi' or `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 August 26,
1998.


File: standards.info,  Node: Intellectual Property,  Next: Design Advice,  Prev: Preface,  Up: Top

Keeping Free Software Free
**************************

   This node discusses how you can make sure that GNU software remains
unencumbered.

* Menu:

* Reading Non-Free Code::       Referring to Proprietary Programs
* Contributions::               Accepting Contributions


File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Up: Intellectual Property

Referring to Proprietary Programs
=================================

   Don't in any circumstances refer to Unix source code for or during
your work on GNU!  (Or to any other proprietary programs.)

   If you have a vague recollection of the internals of a Unix program,
this does not absolutely mean you can't write an imitation of it, but
do try to organize the imitation internally along different lines,
because this is likely to make the details of the Unix version
irrelevant and dissimilar to your results.

   For example, Unix utilities were generally optimized to minimize
memory use; if you go for speed instead, your program will be very
different.  You could keep the entire input file in core and scan it
there instead of using stdio.  Use a smarter algorithm discovered more
recently than the Unix program.  Eliminate use of temporary files.  Do
it in one pass instead of two (we did this in the assembler).

   Or, on the contrary, emphasize simplicity instead of speed.  For some
applications, the speed of today's computers makes simpler algorithms
adequate.

   Or go for generality.  For example, Unix programs often have static
tables or fixed-size strings, which make for arbitrary limits; use
dynamic allocation instead.  Make sure your program handles NULs and
other funny characters in the input files.  Add a programming language
for extensibility and write part of the program in that language.

   Or turn some parts of the program into independently usable
libraries.  Or use a simple garbage collector instead of tracking
precisely when to free memory, or use a new GNU facility such as
obstacks.


File: standards.info,  Node: Contributions,  Prev: Reading Non-Free Code,  Up: Intellectual Property

Accepting Contributions
=======================

   If someone else sends you a piece of code to add to the program you
are working on, we need legal papers to use it--the same sort of legal
papers we will need to get from you.  *Each* significant contributor to
a program must sign some sort of legal papers in order for us to have
clear title to the program.  The main author alone is not enough.

   So, before adding in any contributions from other people, please tell
us, so we can arrange to get the papers.  Then wait until we tell you
that we have received the signed papers, before you actually use the
contribution.

   This applies both before you release the program and afterward.  If
you receive diffs to fix a bug, and they make significant changes, we
need legal papers for that change.

   This also applies to comments and documentation files.  For copyright
law, comments and code are just text.  Copyright applies to all kinds of
text, so we need legal papers for all kinds.

   You don't need papers for changes of a few lines here or there, since
they are not significant for copyright purposes.  Also, you don't need
papers if all you get from the suggestion is some ideas, not actual code
which you use.  For example, if you write a different solution to the
problem, you don't need to get papers.

   We know this is frustrating; it's frustrating for us as well.  But if
you don't wait, you are going out on a limb--for example, what if the
contributor's employer won't sign a disclaimer?  You might have to take
that code out again!

   The very worst thing is if you forget to tell us about the other
contributor.  We could be very embarrassed in court some day as a
result.

   We have more detailed advice for maintainers of programs; if you have
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy.


File: standards.info,  Node: Design Advice,  Next: Program Behavior,  Prev: Intellectual Property,  Up: Top

General Program Design
**********************

   This node discusses some of the issues you should take into account
when designing your program.

* Menu:

* Compatibility::               Compatibility with other implementations
* Using Extensions::            Using non-standard features
* ANSI C::                      Using ANSI C features
* Source Language::             Using languages other than C


File: standards.info,  Node: Compatibility,  Next: Using Extensions,  Up: Design Advice

Compatibility with Other Implementations
========================================

   With occasional exceptions, utility programs and libraries for GNU
should be upward compatible with those in Berkeley Unix, and upward
compatible with ANSI C if ANSI C specifies their behavior, and upward
compatible with POSIX if POSIX specifies their behavior.

   When these standards conflict, it is useful to offer compatibility
modes for each of them.

   ANSI C and POSIX prohibit many kinds of extensions.  Feel free to
make the extensions anyway, and include a `--ansi', `--posix', or
`--compatible' option to turn them off.  However, if the extension has
a significant chance of breaking any real programs or scripts, 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 `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,
`vi' is replaced with Emacs.)  But it is nice to offer a compatible
feature as well.  (There is a free `vi' clone, so we offer it.)

   Additional useful features not in Berkeley Unix are welcome.


File: standards.info,  Node: Using Extensions,  Next: ANSI C,  Prev: Compatibility,  Up: Design Advice

Using Non-standard Features
===========================

   Many GNU facilities that already exist support a number of convenient
extensions over the comparable Unix facilities.  Whether to use these
extensions in implementing your program is a difficult question.

   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 program to
work on fewer kinds of machines.

   With some extensions, it might be easy to provide both alternatives.
For example, you can define functions with a "keyword" `INLINE' and
define that as a macro to expand into either `inline' or nothing,
depending on the compiler.

   In general, perhaps it is best not to use the extensions if you can
straightforwardly do without them, but to use the extensions if they
are a big improvement.

   An exception to this rule are the large, established programs (such
as Emacs) which run on a great variety of systems.  Such programs would
be broken by use of GNU extensions.

   Another exception is for programs that are used as part of
compilation: anything that must be compiled with other compilers in
order to bootstrap the GNU compilation facilities.  If these require
the GNU compiler, then no one can compile them without having them
installed already.  That would be no good.


File: standards.info,  Node: ANSI C,  Next: Source Language,  Prev: Using Extensions,  Up: Design Advice

ANSI C and pre-ANSI C
=====================

   Do not ever use the "trigraph" feature of ANSI C.

   ANSI C is widespread enough now that it is ok to write new programs
that use ANSI C features (and therefore will not work in non-ANSI
compilers).  And if a program is already written in ANSI C, there's no
need to convert it to support non-ANSI compilers.

   However, it is easy to support non-ANSI compilers in most programs,
so you might still consider doing so when you write a program.  Instead
of writing function definitions in ANSI prototype form,

     int
     foo (int x, int y)
     ...

write the definition in pre-ANSI style like this,

     int
     foo (x, y)
          int x, y;
     ...

and use a separate declaration to specify the argument prototype:

     int foo (int, int);

   You need such a declaration anyway, in a header file, to get the
benefit of ANSI C prototypes in all the files where the function is
called.  And once you have it, you lose nothing by writing the function
definition in the pre-ANSI style.

   If you don't know non-ANSI C, there's no need to learn it; just
write in ANSI C.


File: standards.info,  Node: Source Language,  Prev: ANSI C,  Up: Design Advice

Using Languages Other Than C
============================

   Using a language other than C is like using a non-standard feature:
it will cause trouble for users.  Even if GCC supports the other
language, users may find it inconvenient to have to install the
compiler for that other language in order to build your program.  For
example, if you write your program in C++, people will have to install
the C++ compiler in order to compile your program.  Thus, it is better
if you write in C.

   But there are three situations when there is no disadvantage in using
some other language:

   * It is okay to use another language if your program contains an
     interpreter for that language.

     For example, if your program links with GUILE, it is ok to write
     part of the program in Scheme or another language supported by
     GUILE.

   * It is okay to use another language in a tool specifically intended
     for use with that language.

     This is okay because the only people who want to build the tool
     will be those who have installed the other language anyway.

   * If an application is of interest to a narrow community, then
     perhaps it's not important if the application is inconvenient to
     install.

   C has one other advantage over C++ and other compiled languages: more
people know C, so more people will find it easy to read and modify the
program if it is written in C.


File: standards.info,  Node: Program Behavior,  Next: Writing C,  Prev: Design Advice,  Up: Top

Program Behavior for All Programs
*********************************

   This node describes how to write robust software. It also describes
general standards for error messages, the command line interface, and
how libraries should behave.

* Menu:

* Semantics::                   Writing robust programs
* Libraries::                   Library behavior
* Errors::                      Formatting error messages
* User Interfaces::             Standards for command line interfaces
* Option Table::                Table of long options.
* Memory Usage::                When and how to care about memory needs


File: standards.info,  Node: Semantics,  Next: Libraries,  Up: Program Behavior

Writing Robust Programs
=======================

   Avoid arbitrary limits on the length or number of *any* data
structure, including file names, lines, files, and symbols, by
allocating all data structures dynamically.  In most Unix utilities,
"long lines are silently truncated".  This is not acceptable in a GNU
utility.

   Utilities reading files should not drop NUL characters, or any other
nonprinting characters *including those with codes above 0177*.  The
only sensible exceptions would be utilities specifically intended for
interface to certain types of printers that can't handle those
characters.

   Check every system call for an error return, unless you know you
wish to ignore errors.  Include the system error text (from `perror' or
equivalent) in *every* error message resulting from a failing system
call, as well as the name of the file if any and the name of the
utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.

   Check every call to `malloc' or `realloc' to see if it returned
zero.  Check `realloc' even if you are making the block smaller; in a
system that rounds block sizes to a power of 2, `realloc' may get a
different block if you ask for less space.

   In Unix, `realloc' can destroy the storage block if it returns zero.
GNU `realloc' does not have this bug: if it fails, the original block
is unchanged.  Feel free to assume the bug is fixed.  If you wish to
run your program on Unix, and wish to avoid lossage in this case, you
can use the GNU `malloc'.

   You must expect `free' to alter the contents of the block that was
freed.  Anything you want to fetch from the block, you must fetch before
calling `free'.

   If `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.  This allows the user to kill other processes to free up
virtual memory, and then try the command again.

   Use `getopt_long' to decode arguments, unless the argument syntax
makes this unreasonable.

   When static storage is to be written in during program execution, use
explicit C code to initialize it.  Reserve C initialized declarations
for data that will not be changed.

   Try to avoid low-level interfaces to obscure Unix data structures
(such as file directories, utmp, or the layout of kernel memory), since
these are less likely to work compatibly.  If you need to find all the
files in a directory, use `readdir' or some other high-level interface.
These will be supported compatibly by GNU.

   The preferred signal handling facilities are the BSD variant of
`signal', and the POSIX `sigaction' function; the alternative USG
`signal' interface is an inferior design.

   Nowadays, using the POSIX signal functions may be the easiest way to
make a program portable.  If you use `signal', then on GNU/Linux
systems running GNU libc version 1, you should include `bsd/signal.h'
instead of `signal.h', so as to get BSD behavior.  It is up to you
whether to support systems where `signal' has only the USG behavior, or
give up on them.

   In error checks that detect "impossible" conditions, just abort.
There is usually no point in printing any message.  These checks
indicate the existence of bugs.  Whoever wants to fix the bugs will have
to read the source code and run a debugger.  So explain the problem with
comments in the source.  The relevant data will be in variables, which
are easy to examine with the debugger, so there is no point moving them
elsewhere.