Mercurial > hg > octave-kai > gnulib-hg
changeset 14502:19e0538d66eb
autoupdate
author | Karl Berry <karl@freefriends.org> |
---|---|
date | Tue, 29 Mar 2011 09:39:10 -0700 |
parents | 61bd16d184ab |
children | 33d35e3624cd |
files | doc/gendocs_template doc/standards.texi |
diffstat | 2 files changed, 73 insertions(+), 180 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/gendocs_template +++ b/doc/gendocs_template @@ -3,12 +3,6 @@ <!--#include virtual="/server/banner.html" --> <h2>%%TITLE%%</h2> -<!-- This document is in XML, and xhtml 1.0 --> -<!-- Please make sure to properly nest your tags --> -<!-- and ensure that your final document validates --> -<!-- consistent with W3C xhtml 1.0 and CSS standards --> -<!-- See validator.w3.org --> - <address>Free Software Foundation</address> <address>last updated %%DATE%%</address>
--- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate January 27, 2011 +@set lastupdate March 28, 2011 @c %**end of header @dircategory GNU organization @@ -50,8 +50,8 @@ @contents @ifnottex -@node Top, Preface, (dir), (dir) -@top Version +@node Top +@top GNU Coding Standards @insertcopying @end ifnottex @@ -701,7 +701,8 @@ @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 @@ -2831,6 +2832,7 @@ programs. @code{doschk} also reports file names longer than 14 characters. + @node System Portability @section Portability between System Types @cindex portability, between system types @@ -2912,9 +2914,9 @@ @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 @@ -2945,51 +2947,6 @@ @} @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 @@ -3000,133 +2957,75 @@ 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 - -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. +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 + +@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. + @node Internationalization @section Internationalization