@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate March 26, 1999
+@set lastupdate March 2, 2000
@c %**end of header
@ifinfo
@chapter Keeping Free Software Free
This @value{CHAPTER} discusses how you can make sure that GNU software
-remains unencumbered.
+avoids legal difficulties, and other related issues.
@menu
* Reading Non-Free Code:: Referring to Proprietary Programs
* Contributions:: Accepting Contributions
+* Trademarks:: How We Deal with Trademark Issues
@end menu
@node Reading Non-Free Code
Or use a simple garbage collector instead of tracking precisely when
to free memory, or use a new GNU facility such as obstacks.
-
@node Contributions
@section Accepting Contributions
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy.
+@node Trademarks
+@section Trademarks
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them. There is no legal requirement for them.
+
+What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities. For example, since ``Objective C'' is
+(or at least was) a trademark, we made sure to say that we provide a
+``compiler for the Objective C language'' rather than an ``Objective C
+compiler''. The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using ``Objective C'' as a label for the compiler rather than for the
+language.
+
@node Design Advice
@chapter General Program Design
This @value{CHAPTER} discusses some of the issues you should take into
account when designing your program.
+@c Standard or ANSI C
+@c
+@c In 1989 the American National Standards Institute (ANSI) standardized
+@c C as standard X3.159-1989. In December of that year the
+@c International Standards Organization ISO adopted the ANSI C standard
+@c making minor changes. In 1990 ANSI then re-adopted ISO standard
+@c C. This version of C is known as either ANSI C or Standard C.
+
@menu
+* Source Language:: Which languges to use.
* Compatibility:: Compatibility with other implementations
* Using Extensions:: Using non-standard features
-* ANSI C:: Using ANSI C features
-* Source Language:: Using languages other than C
+* Standard C:: Using Standard (ANSI 1989) C features
@end menu
+@node Source Language
+@section Which Languages to Use
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language 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 GNU C++ compiler in order to compile your program.
+
+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.
+
+So in general it is much better to use use C, rather than the
+comparable alternatives.
+
+But there are two exceptions to that conclusion:
+
+@itemize @bullet
+@item
+It is no problem to use another language to write a tool specifically
+intended for use with that language. That is because the only people
+who want to build the tool will be those who have installed the other
+language anyway.
+
+@item
+If an application is of interest only to a narrow part of the community,
+then the question of which language it is written in has less effect on
+other people, so you may as well please yourself.
+@end itemize
+
+Many programs are designed to be extensible: they include an interpreter
+for a language that is higher level than C. Often much of the program
+is written in that language, too. The Emacs editor pioneered this
+technique.
+
+The standard extensibility interpreter for GNU software is GUILE, which
+implements the language Scheme (an especially clean and simple dialect
+of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject
+programs written in other ``scripting languages'' such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
@node Compatibility
@section 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 @sc{ansi} C if @sc{ansi} C specifies their behavior, and
-upward compatible with @sc{posix} if @sc{posix} specifies their
-behavior.
+compatible with 1989 Standard C if 1989 Standard C specifies their
+behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+their behavior.
When these standards conflict, it is useful to offer compatibility
modes for each of them.
-@sc{ansi} C and @sc{posix} prohibit many kinds of extensions. Feel free
-to make the extensions anyway, and include a @samp{--ansi},
+1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
+free to make the extensions anyway, and include a @samp{--ansi},
@samp{--posix}, or @samp{--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.
+programs or scripts, then it is not really upward compatible. So you
+should try to redesign its interface to make it upward compatible.
Many GNU programs suppress extensions that conflict with @sc{posix} if the
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
@code{vi} is replaced with Emacs.) But it is nice to offer a compatible
feature as well. (There is a free @code{vi} clone, so we offer it.)
-Additional useful features not in Berkeley Unix are welcome.
+Additional useful features are welcome regardless of whether
+there is any precedent for them.
@node Using Extensions
@section Using Non-standard Features
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.
+Emacs) which run on a great variety of systems. Using GNU extensions in
+such programs would make many users unhappy, so we don't do that.
-@node ANSI C
-@section @sc{ansi} C and pre-@sc{ansi} C
+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 extremely troublesome in certain cases.
-Do not ever use the ``trigraph'' feature of @sc{ansi} C.
+@node Standard C
+@section 1989 Standard C and Pre-Standard C
-@sc{ansi} C is widespread enough now that it is ok to write new programs
-that use @sc{ansi} C features (and therefore will not work in
-non-@sc{ansi} compilers). And if a program is already written in
-@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
-compilers.
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+``trigraph'' feature of 1989 Standard C.
-If you don't know non-@sc{ansi} C, there's no need to learn it; just
-write in @sc{ansi} C.
+However, it is easy to support pre-standard compilers in most programs,
+so if you know how to do that, feel free. If a program you are
+maintaining has such support, you should try to keep it working.
-However, it is easy to support non-@sc{ansi} compilers in most programs,
-so you might still consider doing so when you write a program. And if a
-program you are maintaining has such support, you should try to keep it
-working.
-
-To support pre-@sc{ansi} C, instead of writing function definitions in
-@sc{ansi} prototype form,
+To support pre-standard C, instead of writing function definitions in
+standard prototype form,
@example
int
@end example
@noindent
-write the definition in pre-@sc{ansi} style like this,
+write the definition in pre-standard style like this,
@example
int
@end example
You need such a declaration anyway, in a header file, to get the benefit
-of @sc{ansi} C prototypes in all the files where the function is called.
-And once you have the declaration, you normally lose nothing by writing
-the function definition in the pre-@sc{ansi} style.
+of prototypes in all the files where the function is called. And once
+you have the declaration, you normally lose nothing by writing the
+function definition in the pre-standard style.
This technique does not work for integer types narrower than @code{int}.
If you think of an argument as being of a type narrower than @code{int},
@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
@code{int} on some machines; but you cannot use @code{int} instead,
because @code{dev_t} is wider than @code{int} on some machines. There
-is no type you can safely use on all machines in a non-@sc{ansi}
-definition. The only way to support non-@sc{ansi} C and pass such an
+is no type you can safely use on all machines in a non-standard
+definition. The only way to support non-standard C and pass such an
argument is to check the width of @code{dev_t} using Autoconf and choose
the argument type accordingly. This may not be worth the trouble.
-@node Source Language
-@section 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:
-
-@itemize @bullet
-@item
-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.
-
-@item
-It is okay to use another language in a tool specifically intended for
-use with that language.
+In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
-This is okay because the only people who want to build the tool will be
-those who have installed the other language anyway.
-
-@item
-If an application is of interest to a narrow community, then perhaps
-it's not important if the application is inconvenient to install.
-@end itemize
-
-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.
+@example
+/* Declare the prototype for a general external function. */
+#if defined (__STDC__) || defined (WINDOWSNT)
+#define P_(proto) proto
+#else
+#define P_(proto) ()
+#endif
+@end example
@node Program Behavior
@chapter Program Behavior for All Programs
-This @value{CHAPTER} describes how to write robust software. It also
-describes general standards for error messages, the command line interface,
-and how libraries should behave.
+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
@var{source-file-name}:@var{lineno}: @var{message}
@end example
+@noindent
+If you want to mention the column number, use this format:
+
+@example
+@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.
+
Error messages from other noninteractive programs should look like this:
@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
@item hide-control-chars
@samp{-q} in @code{ls}.
+@item html
+In @code{makeinfo}, output HTML.
+
@item idle
@samp{-u} in @code{who}.
@item info
@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+@item init-file
+In some programs, specify the name of the file to read as the user's
+init file.
+
@item initial
@samp{-i} in @code{expand}.
@item only-time
@samp{-F} in @code{gprof}.
+@item options
+@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+@code{fdmountd}, and @code{fdumount}.
+
@item output
In various programs, specify the output file name.
@end example
@noindent
-or, if you want to use @sc{ansi} C, format the definition like this:
+or, if you want to use Standard C syntax, format the definition like
+this:
@example
static char *
@}
@end example
-In @sc{ansi} C, if the arguments don't fit nicely on one line,
+In Standard C, if the arguments don't fit nicely on one line,
split it like this:
@example
@dots{}
@end example
-For the body of the function, we prefer code formatted like this:
+The rest of this section gives our recommendations for other aspects of
+C formatting style. We don't think of them as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+But whatever style you use, please use it consistently, since a mixture
+of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+For the body of the function, our recommended style looks like this:
@example
if (x < foo (y, z))
Insert extra parentheses so that Emacs will indent the code properly.
For example, the following indentation looks nice if you do it by hand,
-but Emacs would mess it up:
@example
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
@end example
-But adding a set of parentheses solves the problem:
+@noindent
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
@example
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
just how long the pages are, since they do not have to fit on a printed
page. The formfeeds should appear alone on lines by themselves.
-
@node Comments
@section Commenting Your Work
Please explicitly declare all arguments to functions.
Don't omit them just because they are @code{int}s.
+Some programmers like to use the GCC @samp{-Wall} option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use @samp{-Wall}, because it gives
+warnings for valid and legitimate code which they do not want to change.
+If you want to do this, then do. The compiler should be your servant,
+not your master.
+
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
when there is a higher-level alternative (@code{readdir}).
As for systems that are not like Unix, such as MSDOS, Windows, the
-Macintosh, VMS, and MVS, supporting them is usually so much work that it
-is better if you don't.
-
-The planned GNU kernel is not finished yet, but you can tell which
-facilities it will provide by looking at the GNU C Library Manual. The
-GNU kernel is based on Mach, so the features of Mach will also be
-available. However, if you use Mach features, you'll probably have
-trouble debugging your program today.
+Macintosh, VMS, and MVS, supporting them is often a lot of work. When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+It is a good idea to define the ``feature test macro''
+@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
+or GNU/Linux, this will enable the declarations of GNU library extension
+functions, and that will usually give you a compiler error message if
+you define the same function names in some other way in your program.
+(You don't have to actually @emph{use} these functions, if you prefer
+to make the program more portable to other systems.)
+
+But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
@node CPU Portability
@section Portability between @sc{cpu}s
When calling functions, you need not worry about the difference between
pointers of various types, or between pointers and integers. On most
machines, there's no difference anyway. As for the few machines where
-there is a difference, all of them support @sc{ansi} C, so you can use
-prototypes (conditionalized to be active only in @sc{ansi} C) to make
-the code work on those systems.
+there is a difference, all of them support 1989 Standard C, so you can
+use prototypes (perhaps conditionalized to be active only in Standard C)
+to make the code work on those systems.
In certain cases, it is ok to pass integer and pointer arguments
indiscriminately to the same function, and use no prototype on any
@noindent
In practice, this works on all machines, since a pointer is generally
-the widest possible kind of argument, and it is much simpler than any
+the widest possible kind of argument; it is much simpler than any
``correct'' alternative. Be sure @emph{not} to use a prototype for such
functions.
-However, avoid casting pointers to integers unless you really need to.
-Outside of special situations, such casts greatly reduce portability,
-and in most programs they are easy to avoid. In the cases where casting
-pointers to integers is essential---such as, a Lisp interpreter which
-stores type information as well as an address in one word---it is ok to
-do it, but you'll have to make explicit provisions to handle different
-word sizes.
+If you have decided to use 1989 Standard C, then you can instead define
+@code{error} using @file{stdarg.h}, and pass the arguments along to
+@code{vfprintf}.
+
+Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential---such as, a Lisp
+interpreter which stores type information as well as an address in one
+word---you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from @code{malloc} starts far away
+from zero.
@node System Functions
@section Calling System Functions
-C implementations differ substantially. @sc{ansi} C reduces but does not
-eliminate the incompatibilities; meanwhile, many users wish to compile
-GNU software with pre-@sc{ansi} compilers. This chapter gives
-recommendations for how to use the more or less standard C library
-functions to avoid unnecessary loss of portability.
+C implementations differ substantially. 1989 Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do. 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
+Don't use the return value of @code{sprintf}. It returns the number of
characters written on some systems, but not on all systems.
+@item
+Be aware that @code{vfprintf} is not always available.
+
@item
@code{main} should be declared to return type @code{int}. It should
terminate either by calling @code{exit} or by returning the integer
@item
If you must declare a system function, don't specify the argument types.
-Use an old-style declaration, not an @sc{ansi} prototype. The more you
+Use an old-style declaration, not a Standard C prototype. The more you
specify about the function, the more likely a conflict.
@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 @sc{ansi}
+That causes less of a problem than you might think. The newer standard
string functions should be avoided anyway because many systems still
don't support them. The string functions you can use are these:
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} for new programs, since those are the standard @sc{ansi}
+@code{strrchr} for new programs, since those are the standard
names.) 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
projects / thirdparty / autoconf.git / commitdiff
