lib/gnulib
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/gnulib.git synced 2025-08-20 11:01:20 +03:00
Code Activity

autoupdate

Browse Source
This commit is contained in:
Karl Berry
2011-03-29 09:39:10 -07:00
parent bac631aa62
commit ff2f086830
2 changed files with 62 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/gendocs_template
View File

@@ -3,12 +3,6 @@
<!--#include virtual="/server/banner.html" --> <!--#include virtual="/server/banner.html" -->
<h2>%%TITLE%%</h2> <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>Free Software Foundation</address>
<address>last updated %%DATE%%</address> <address>last updated %%DATE%%</address>

225
doc/standards.texi
View File

@@ -3,7 +3,7 @@
@setfilename standards.info @setfilename standards.info
@settitle GNU Coding Standards @settitle GNU Coding Standards
@c This date is automagically updated when you save this file: @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 @c %**end of header
@dircategory GNU organization @dircategory GNU organization
@@ -50,8 +50,8 @@ Texts. A copy of the license is included in the section entitled
@contents @contents
@ifnottex @ifnottex
@node Top, Preface, (dir), (dir) @node Top
@top Version @top GNU Coding Standards
@insertcopying @insertcopying
@end ifnottex @end ifnottex
@@ -701,7 +701,8 @@ fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
@end example @end example
@noindent @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 In bash, use @code{set -C} (long name @code{noclobber}) to avoid this
problem. In addition, the @code{mktemp} utility is a more general problem. In addition, the @code{mktemp} utility is a more general
@@ -2831,6 +2832,7 @@ GNU programs that have it, but there is no need to do this in new GNU
programs. @code{doschk} also reports file names longer than 14 programs. @code{doschk} also reports file names longer than 14
characters. characters.
@node System Portability @node System Portability
@section Portability between System Types @section Portability between System Types
@cindex portability, between system types @cindex portability, between system types
@@ -2912,9 +2914,9 @@ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
@end example @end example
1989 Standard C requires this to work, and we know of only one 1989 Standard C requires this to work, and we know of only one
counterexample: 64-bit programs on Microsoft Windows. We will counterexample: 64-bit programs on Microsoft Windows. We will leave
leave it to those who want to port GNU programs to that environment it to those who want to port GNU programs to that environment to
to figure out how to do it. figure out how to do it.
Predefined file-size types like @code{off_t} are an exception: they are 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 longer than @code{long} on many platforms, so code like the above won't
@@ -2945,51 +2947,6 @@ while ((c = getchar ()) != EOF)
@} @}
@end example @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 @cindex casting pointers to integers
Avoid casting pointers to integers if you can. Such casts greatly Avoid casting pointers to integers if you can. Such casts greatly
reduce portability, and in most programs they are easy to avoid. In the reduce portability, and in most programs they are easy to avoid. In the
@@ -3000,133 +2957,75 @@ 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 normal range of addresses you can get from @code{malloc} starts far away
from zero. from zero.
@node System Functions @node System Functions
@section Calling System Functions @section Calling System Functions
@cindex C library functions, and portability
@cindex POSIX functions, and portability
@cindex library functions, and portability @cindex library functions, and portability
@cindex portability, and library functions @cindex portability, and library functions
C implementations differ substantially. Standard C reduces but does Historically, C implementations differed substantially, and many
not eliminate the incompatibilities; meanwhile, many GNU packages still systems lacked a full implementation of ANSI/ISO C89. Nowadays,
support pre-standard compilers because this is not hard to do. This however, very few systems lack a C89 compiler and GNU C supports
chapter gives recommendations for how to use the more-or-less standard C almost all of C99. Similarly, most systems implement POSIX.1-1993
library functions to avoid unnecessary loss of portability. libraries and tools, and many have POSIX.1-2001.
@itemize @bullet Hence, there is little reason to support old C or non-POSIX systems,
@item and you may want to take advantage of C99 and POSIX-1.2001 to write
Don't use the return value of @code{sprintf}. It returns the number of clearer, more portable, or faster code. You should use standard
characters written on some systems, but not on all systems. 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.
@item Despite the standards, nearly every library function has some sort of
Be aware that @code{vfprintf} is not always available. portability issue on some system or another. Here are some examples:
@item @table @code
@code{main} should be declared to return type @code{int}. It should @item open
terminate either by calling @code{exit} or by returning the integer Names with trailing @code{/}'s are mishandled on many platforms.
status code; make sure it cannot ever return an undefined value.
@cindex declaration for system functions @item printf
@item @code{long double} may be unimplemented; floating values Infinity and
Don't declare system functions explicitly. NaN are often mishandled; output for large precisions may be
incorrect.
Almost any declaration for a system function is wrong on some system. @item readlink
To minimize conflicts, leave it to the system header files to declare May return @code{int} instead of @code{ssize_t}.
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 @item scanf
practice this works fine for most system library functions on the On Windows, @code{errno} is not set on failure.
systems where this really happens; thus, the disadvantage is only @end table
theoretical. By contrast, actual declarations have frequently caused
actual conflicts.
@item @cindex Gnulib
If you must declare a system function, don't specify the argument types. @uref{http://www.gnu.org/software/gnulib/, Gnulib} is a big help in
Use an old-style declaration, not a Standard C prototype. The more you this regard. Gnulib provides implementations of standard interfaces
specify about the function, the more likely a conflict. 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.
@item @findex xmalloc, in Gnulib
In particular, don't unconditionally declare @code{malloc} or @findex error messages, in Gnulib
@code{realloc}. @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.
Most GNU programs use those functions just once, in functions Gnulib integrates with GNU Autoconf and Automake to remove much of the
conventionally named @code{xmalloc} and @code{xrealloc}. These burden of writing portable code from the programmer: Gnulib makes your
functions call @code{malloc} and @code{realloc}, respectively, and configure script automatically determine what features are missing and
check the results. use the Gnulib code to supply the missing pieces.
Because @code{xmalloc} and @code{xrealloc} are defined in your program, The Gnulib and Autoconf manuals have extensive sections on
you can declare them in other files without any risk of type conflict. portability: @ref{Top,, Introduction, gnulib, Gnulib} and
@pxref{Portable C and C++,,, autoconf, Autoconf}. Please consult them
for many more details.
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.
@node Internationalization @node Internationalization
@section Internationalization @section Internationalization