standards.texi

autoconf 2.59版,可用于redhat系统.用于编译原码,编写makefile文件.

@end example

@node Conditional Compilation
@section Conditional Compilation

When supporting configuration options already known when building your
program we prefer using @code{if (... )} over conditional compilation,
as in the former case the compiler is able to perform more extensive
checking of all possible code paths.

For example, please write

@smallexample
  if (HAS_FOO)
    ...
  else
    ...
@end smallexample

@noindent
instead of:

@smallexample
  #ifdef HAS_FOO
    ...
  #else
    ...
  #endif
@end smallexample

A modern compiler such as GCC will generate exactly the same code in
both cases, and we have been using similar techniques with good success
in several projects.  Of course, the former method assumes that
@code{HAS_FOO} is defined as either 0 or 1.

While this is not a silver bullet solving all portability problems,
and is not always appropriate, following this policy would have saved
GCC developers many hours, or even days, per year.

In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
GCC which cannot be simply used in @code{if( ...)} statements, there is
an easy workaround.  Simply introduce another macro
@code{HAS_REVERSIBLE_CC_MODE} as in the following example:

@smallexample
  #ifdef REVERSIBLE_CC_MODE
  #define HAS_REVERSIBLE_CC_MODE 1
  #else
  #define HAS_REVERSIBLE_CC_MODE 0
  #endif
@end smallexample

@node Program Behavior
@chapter Program Behavior for All Programs

This @value{CHAPTER} describes conventions for writing 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 about interfaces generally
* Graphical Interfaces::        Standards for graphical interfaces
* Command-Line Interfaces::     Standards for command line interfaces
* Option Table::                Table of long options
* Memory Usage::                When and how to care about memory needs
* File Usage::                  Which files to use, and where
@end menu

@node Semantics
@section Writing Robust Programs

@cindex arbitrary limits on data
Avoid arbitrary limits on the length or number of @emph{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.

@cindex @code{NUL} characters
Utilities reading files should not drop NUL characters, or any other
nonprinting characters @emph{including those with codes above 0177}.
The only sensible exceptions would be utilities specifically intended
for interface to certain types of terminals or printers
that can't handle those characters.
Whenever possible, try to make programs work properly with
sequences of bytes that represent multibyte characters, using encodings
such as UTF-8 and others.

@cindex error messages
Check every system call for an error return, unless you know you wish to
ignore errors.  Include the system error text (from @code{perror} or
equivalent) in @emph{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.

@cindex @code{malloc} return value
@cindex memory allocation failure
Check every call to @code{malloc} or @code{realloc} to see if it
returned zero.  Check @code{realloc} even if you are making the block
smaller; in a system that rounds block sizes to a power of 2,
@code{realloc} may get a different block if you ask for less space.

In Unix, @code{realloc} can destroy the storage block if it returns
zero.  GNU @code{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 @code{malloc}.

You must expect @code{free} to alter the contents of the block that was
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.  This allows the user to kill other processes to free up
virtual memory, and then try the command again.

@cindex command-line arguments, decoding
Use @code{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.
@c ADR: why?

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 @code{readdir} or some other high-level interface.
These are supported compatibly by GNU.

@cindex signal handling
The preferred signal handling facilities are the BSD variant of
@code{signal}, and the @sc{posix} @code{sigaction} function; the
alternative USG @code{signal} interface is an inferior design.

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

@cindex impossible conditions
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.

Do not use a count of errors as the exit status for a program.
@emph{That does not work}, because exit status values are limited to 8
bits (0 through 255).  A single run of the program might have 256
errors; if you try to return 256 as the exit status, the parent process
will see 0 as the status, and it will appear that the program succeeded.

@cindex temporary files
@cindex @code{TMPDIR} environment variable
If you make temporary files, check the @code{TMPDIR} environment
variable; if that variable is defined, use the specified directory
instead of @file{/tmp}.

In addition, be aware that there is a possible security problem when
creating temporary files in world-writable directories.  In C, you can
avoid this problem by creating temporary files in this manner:

@example
fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
@end example

@noindent
or by using the @code{mkstemps} function from libiberty.

In bash, use @code{set -C} to avoid this problem.

@node Libraries
@section Library Behavior
@cindex libraries

Try to make library functions reentrant.  If they need to do dynamic
storage allocation, at least try to avoid any nonreentrancy aside from
that of @code{malloc} itself.

Here are certain name conventions for libraries, to avoid name
conflicts.

Choose a name prefix for the library, more than two characters long.
All external function and variable names should start with this
prefix.  In addition, there should only be one of these in any given
library member.  This usually means putting each one in a separate
source file.

An exception can be made when two external symbols are always used
together, so that no reasonable program could use one without the
other; then they can both go in the same file.

External symbols that are not documented entry points for the user
should have names beginning with @samp{_}.  The @samp{_} should be
followed by the chosen name prefix for the library, to prevent
collisions with 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
fit any naming convention.

@node Errors
@section Formatting Error Messages
@cindex formatting error messages
@cindex error messages, formatting

Error messages from compilers should look like this:

@example
@var{source-file-name}:@var{lineno}: @var{message}
@end example

@noindent
If you want to mention the column number, use one of these formats:

@example
@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
@var{source-file-name}:@var{lineno}.@var{column}: @var{message}   

@end example

@noindent
Line numbers should start from 1 at the beginning of the file, and
column numbers should start from 1 at the beginning of the line.  (Both
of these conventions are chosen for compatibility.)  Calculate column
numbers assuming that space and all ASCII printing characters have
equal width, and assuming tab stops every 8 columns.

The error message can also give both the starting and ending positions
of the erroneous text.  There are several formats so that you can
avoid redundant information such as a duplicate line number.
Here are the possible formats:

@example
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
@end example

@noindent
When an error is spread over several files, you can use this format:

@example
@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
@end example

Error messages from other noninteractive programs should look like this:

@example
@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
@end example

@noindent
when there is an appropriate source file, or like this:

@example
@var{program}: @var{message}
@end example

@noindent
when there is no relevant source file.

If you want to mention the column number, use this format:

@example
@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
@end example

In an interactive program (one that is reading commands from a
terminal), it is better not to include the program name in an error
message.  The place to indicate which program is running is in the
prompt or with the screen layout.  (When the same program runs with
input from a source other than a terminal, it is not interactive and
would do best to print error messages using the noninteractive style.)

The string @var{message} should not begin with a capital letter when
it follows a program name and/or file name, because that isn't the
beginning of a sentence.  (The sentence conceptually starts at the
beginning of the line.)  Also, it should not end with a period.

Error messages from interactive programs, and other messages such as
usage messages, should start with a capital letter.  But they should not
end with a period.

@node User Interfaces
@section Standards for Interfaces Generally

@cindex program name and its behavior
@cindex behavior, dependent on program's name
Please don't make the behavior of a utility depend on the name used
to invoke it.  It is useful sometimes to make a link to a utility
with a different name, and that should not change what it does.

Instead, use a run time option or a compilation switch or both
to select among the alternate behaviors.

@cindex output device and program's behavior
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.  (Variation in error
message syntax when using a terminal is ok, because that is a side issue
that people do not depend on.)

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.

@node Graphical Interfaces
@section Standards for Graphical Interfaces
@cindex graphical user interface

@cindex gtk
When you write a program that provides a graphical user interface,
please make it work with X Windows and the GTK toolkit unless the
functionality specifically requires some alternative (for example,
``displaying jpeg images while in console mode'').

In addition, please provide a command-line interface to control the
functionality.  (In many cases, the graphical user interface can be a
separate program which invokes the command-line program.)  This is
so that the same jobs can be done from scripts.

@cindex corba
@cindex gnome
Please also consider providing a CORBA interface (for use from GNOME), a
library interface (for use from C), and perhaps a keyboard-driven
console interface (for use by users from console mode).  Once you are
doing the work to provide the functionality and the graphical interface,
these won't be much extra work.

@node Command-Line Interfaces
@section Standards for Command Line Interfaces
@cindex command-line interface

@findex getopt
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}
will normally permit options anywhere among the arguments unless the
special argument @samp{--} is used.  This is not what @sc{posix}
specifies; it is a GNU extension.

@cindex long-named options
Please define long-named options that are equivalent to the
single-letter Unix-style options.  We hope to make GNU more user
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 (@pxref{Option 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} or @samp{--output}).  Even if you allow an output
file name as an ordinary argument for compatibility, try to provide an
option as another way to specify it.  This will lead to more consistency
among GNU utilities, and fewer idiosyncracies for users to remember.

@cindex standard command-line options
@cindex options, standard command-line
@cindex CGI programs, standard options for
@cindex PATH_INFO, specifying standard options as
All programs should support two standard options: @samp{--version}
and @samp{--help}.  CGI programs should accept these as command-line
options, and also if given as the @env{PATH_INFO}; for instance,
visiting @url{http://example.org/p.cgi/--help} in a browser should
output the same information as inokving @samp{p.cgi --help} from the
command line.

@table @code
@cindex @samp{--version} option
@item --version
This option should direct the program to print information about its name,
version, origin and legal status, all on standard output, and then exit
successfully.  Other options and arguments should be ignored once this
is seen, and the program should not perform its normal function.

@cindex canonical name of a program
@cindex program's canonical name
The first line is meant to be easy for a program to parse; the version
number proper starts after the last space.  In addition, it contains
the canonical name for this program, in this format:

@example
GNU Emacs 19.30
@end example

@noindent
The program's name should be a constant string; @emph{don't} compute it
from @code{argv[0]}.  The idea is to state the standard or canonical
name for the program, not its file name.  There are other ways to find
out the precise file name where a command is found in @code{PATH}.

If the program is a subsidiary part of a larger package, mention the
package name in parentheses, like this:

@example
emacsserver (GNU Emacs) 19.30
@end example

@noindent
If the package has a version number which is different from this
program's version number, you can mention the package version number
just before the close-parenthesis.

If you @strong{need} to mention the version numbers of libraries which
are distributed separately from the package which contains this program,
you can do so by printing an additional line of version info for each
library you want to mention.  Use the same format for these lines as for
the first line.

Please do not mention all of the libraries that the program uses ``just
for completeness''---that would produce a lot of unhelpful clutter.
Please mention library version numbers only if you find in practice that
they are very important to you in debugging.

The following line, after the version number line or lines, should be a
copyright notice.  If more than one copyright notice is called for, put
each on a separate line.

Next should follow a brief statement that the program is free software,
and that users are free to copy and change it on certain conditions.  If
the program is covered by the GNU GPL, say so here.  Also mention that
there is no warranty, to the extent permitted by law.

It is ok to finish the output with a list of the major authors of the
program, as a way of giving credit.

Here's an example of output that follows these rules:

@smallexample
GNU Emacs 19.34.5
Copyright (C) 1996 Free Software Foundation, Inc.
GNU Emacs comes with NO WARRANTY,
to the extent permitted by law.
You may redistribute copies of GNU Emacs
under the terms of the GNU General Public License.
For more information about these matters,
see the files named COPYING.