@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate August 24, 2010
+@set lastupdate March 28, 2011
@c %**end of header
@dircategory GNU organization
The GNU coding standards, last updated @value{lastupdate}.
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
-Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@contents
@ifnottex
-@node Top, Preface, (dir), (dir)
-@top Version
+@node Top
+@top GNU Coding Standards
@insertcopying
@end ifnottex
@end example
@noindent
-or by using the @code{mkstemps} function from libiberty.
+or by using the @code{mkstemps} function from Gnulib
+(@pxref{mkstemps,,, gnulib, Gnulib}).
+
+In bash, use @code{set -C} (long name @code{noclobber}) to avoid this
+problem. In addition, the @code{mktemp} utility is a more general
+solution for creating temporary files from shell scripts
+(@pxref{mktemp invocation,,, coreutils, GNU Coreutils}).
-In bash, use @code{set -C} to avoid this problem.
@node Libraries
@section Library Behavior
If your program creates complicated data structures, just make them in
memory and give a fatal error if @code{malloc} returns zero.
+@pindex valgrind
+@cindex memory leak
+Memory leak detectors such as @command{valgrind} can be useful, but
+don't complicate a program merely to avoid their false alarms. For
+example, if memory is used until just before a process exits, don't
+free it simply to silence a leak detector.
+
@node File Usage
@section File Usage
@cindex file usage
If you want to do this, then do. The compiler should be your servant,
not your master.
+@pindex clang
+@pindex lint
+Don't make the program ugly just to placate static analysis tools such
+as @command{lint}, @command{clang}, and GCC with extra warnings
+options such as @option{-Wconversion} and @option{-Wundef}. These
+tools can help find bugs and unclear code, but they can also generate
+so many false alarms that that it hurts readability to silence them
+with unnecessary casts, wrappers, and other complications. For
+example, please don't insert casts to @code{void} or calls to
+do-nothing functions merely to pacify a lint checker.
+
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
all its uses. This makes the program even cleaner.
Don't use local variables or parameters that shadow global identifiers.
+GCC's @samp{-Wshadow} option can detect this problem.
@cindex multiple variables in a line
Don't declare multiple variables in one declaration that spans lines.
fatal ("virtual memory exhausted");
@end example
-@pindex lint
-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, except when calling a varargs function.
+This example uses zero without a cast as a null pointer constant.
+This is perfectly fine, except that a cast is needed when calling a
+varargs function or when using @code{sizeof}.
@node Names
@section Naming Variables, Functions, and Files
programs. @code{doschk} also reports file names longer than 14
characters.
+
@node System Portability
@section Portability between System Types
@cindex portability, between system types
@end example
1989 Standard C requires this to work, and we know of only one
-counterexample: 64-bit programs on Microsoft Windows. We will
-leave it to those who want to port GNU programs to that environment
-to figure out how to do it.
+counterexample: 64-bit programs on Microsoft Windows. We will leave
+it to those who want to port GNU programs to that environment to
+figure out how to do it.
Predefined file-size types like @code{off_t} are an exception: they are
longer than @code{long} on many platforms, so code like the above won't
@}
@end example
-It used to be ok to not worry about the difference between pointers
-and integers when passing arguments to functions. However, on most
-modern 64-bit machines pointers are wider than @code{int}.
-Conversely, integer types like @code{long long int} and @code{off_t}
-are wider than pointers on most modern 32-bit machines. Hence it's
-often better nowadays to use prototypes to define functions whose
-argument types are not trivial.
-
-In particular, if functions accept varying argument counts or types
-they should be declared using prototypes containing @samp{...} and
-defined using @file{stdarg.h}. For an example of this, please see the
-@uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
-declares and defines the following function:
-
-@example
-/* Print a message with `fprintf (stderr, FORMAT, ...)';
- if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
- If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
-
-void error (int status, int errnum, const char *format, ...);
-@end example
-
-A simple way to use the Gnulib error module is to obtain the two
-source files @file{error.c} and @file{error.h} from the Gnulib library
-source code repository at
-@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=gnulib.git}.
-Here's a sample use:
-
-@example
-#include "error.h"
-#include <errno.h>
-#include <stdio.h>
-
-char *program_name = "myprogram";
-
-FILE *
-xfopen (char const *name)
-@{
- FILE *fp = fopen (name, "r");
- if (! fp)
- error (1, errno, "cannot read %s", name);
- return fp;
-@}
-@end example
-
@cindex casting pointers to integers
Avoid casting pointers to integers if you can. Such casts greatly
reduce portability, and in most programs they are easy to avoid. In the
normal range of addresses you can get from @code{malloc} starts far away
from zero.
+
@node System Functions
@section Calling System Functions
+
+@cindex C library functions, and portability
+@cindex POSIX functions, and portability
@cindex library functions, and portability
@cindex portability, and library functions
-C implementations differ substantially. 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 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
-status code; make sure it cannot ever return an undefined value.
-
-@cindex declaration for system functions
-@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; thus, the disadvantage 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 a Standard C 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.
-
-@cindex string library functions
-@item
-The string functions require special treatment. Some Unix systems have
-a header file @file{string.h}; others 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 standard
-string functions should be avoided 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} 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
-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
+Historically, C implementations differed substantially, and many
+systems lacked a full implementation of ANSI/ISO C89. Nowadays,
+however, very few systems lack a C89 compiler and GNU C supports
+almost all of C99. Similarly, most systems implement POSIX.1-1993
+libraries and tools, and many have POSIX.1-2001.
+
+Hence, there is little reason to support old C or non-POSIX systems,
+and you may want to take advantage of C99 and POSIX-1.2001 to write
+clearer, more portable, or faster code. You should use standard
+interfaces where possible; but if GNU extensions make your program
+more maintainable, powerful, or otherwise better, don't hesitate to
+use them. In any case, don't make your own declaration of system
+functions; that's a recipe for conflict.
+
+Despite the standards, nearly every library function has some sort of
+portability issue on some system or another. Here are some examples:
+
+@table @code
+@item open
+Names with trailing @code{/}'s are mishandled on many platforms.
+
+@item printf
+@code{long double} may be unimplemented; floating values Infinity and
+NaN are often mishandled; output for large precisions may be
+incorrect.
+
+@item readlink
+May return @code{int} instead of @code{ssize_t}.
+
+@item scanf
+On Windows, @code{errno} is not set on failure.
+@end table
-char *strchr ();
-char *strrchr ();
-@end example
-@end itemize
+@cindex Gnulib
+@uref{http://www.gnu.org/software/gnulib/, Gnulib} is a big help in
+this regard. Gnulib provides implementations of standard interfaces
+on many of the systems that lack them, including portable
+implementations of enhanced GNU interfaces, thereby making their use
+portable, and of POSIX-1.2008 interfaces, some of which are missing
+even on up-to-date GNU systems.
+
+@findex xmalloc, in Gnulib
+@findex error messages, in Gnulib
+@findex data structures, in Gnulib
+Gnulib also provides many useful non-standard interfaces; for example,
+C implementations of standard data structures (hash tables, binary
+trees), error-checking type-safe wrappers for memory allocation
+functions (@code{xmalloc}, @code{xrealloc}), and output of error
+messages.
+
+Gnulib integrates with GNU Autoconf and Automake to remove much of the
+burden of writing portable code from the programmer: Gnulib makes your
+configure script automatically determine what features are missing and
+use the Gnulib code to supply the missing pieces.
+
+The Gnulib and Autoconf manuals have extensive sections on
+portability: @ref{Top,, Introduction, gnulib, Gnulib} and
+@pxref{Portable C and C++,,, autoconf, Autoconf}. Please consult them
+for many more details.
-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 Internationalization
@section Internationalization
projects / gnulib.git / blobdiff