[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

gnustandards ChangeLog standards.texi

From: Karl Berry
Subject: gnustandards ChangeLog standards.texi
Date: Mon, 28 Mar 2011 22:56:55 +0000

CVSROOT:        /sources/gnustandards
Module name:    gnustandards
Changes by:     Karl Berry <karl>       11/03/28 22:56:55

Modified files:
        .              : ChangeLog standards.texi 

Log message:
        update for current code portability concerns


Index: ChangeLog
RCS file: /sources/gnustandards/gnustandards/ChangeLog,v
retrieving revision 1.135
retrieving revision 1.136
diff -u -b -r1.135 -r1.136
--- ChangeLog   29 Jan 2011 00:39:24 -0000      1.135
+++ ChangeLog   28 Mar 2011 22:56:55 -0000      1.136
@@ -1,3 +1,17 @@
+2011-03-28  Karl Berry  <address@hidden>
+       * standards.texi (Top): fix @top to be the real title, not the
+       spurious "Version".
+       (Semantics): mkstemps is better to take from Gnulib these days,
+       not libiberty.
+       (CPU Portability): <stdarg.h> is required these days, no need to
+       explicitly mention using it.
+       (System Functions): rewrite to describe current problems and Gnulib.
+       These changes suggested by Reuben Thomas.
+       * work.m/GNUmakefile,
+       * work.s/GNUmakefile: simplify HTML update methods.
 2011-01-28  Karl Berry  <address@hidden>
        * standards.texi (Semantics): more info about robust temporary

Index: standards.texi
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.202
retrieving revision 1.203
diff -u -b -r1.202 -r1.203
--- standards.texi      29 Jan 2011 00:39:24 -0000      1.202
+++ standards.texi      28 Mar 2011 22:56:55 -0000      1.203
@@ -3,7 +3,7 @@
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
address@hidden lastupdate January 27, 2011
address@hidden lastupdate March 28, 2011
 @c %**end of header
 @dircategory GNU organization
@@ -50,8 +50,8 @@
address@hidden Top, Preface, (dir), (dir)
address@hidden Version
address@hidden Top
address@hidden GNU Coding Standards
 @end ifnottex
@@ -701,7 +701,8 @@
 @end example
-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
 @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
address@hidden://, Gnulib} error module, which
-declares and defines the following function:
-/* 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, ...);
address@hidden 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
-Here's a sample use:
-#include "error.h"
-#include <errno.h>
-#include <stdio.h>
-char *program_name = "myprogram";
-xfopen (char const *name)
-  FILE *fp = fopen (name, "r");
-  if (! fp)
-    error (1, errno, "cannot read %s", name);
-  return fp;
address@hidden 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
address@hidden C library functions, and portability
address@hidden 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.
address@hidden @bullet
-Don't use the return value of @code{sprintf}.  It returns the number of
-characters written on some systems, but not on all systems.
-Be aware that @code{vfprintf} is not always available.
address@hidden 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.
+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:
address@hidden @code
address@hidden open
+Names with trailing @code{/}'s are mishandled on many platforms.
address@hidden printf
address@hidden double} may be unimplemented; floating values Infinity and
+NaN are often mishandled; output for large precisions may be
address@hidden declaration for system functions
-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.
address@hidden readlink
+May return @code{int} instead of @code{ssize_t}.
-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.
-In particular, don't unconditionally declare @code{malloc} or
-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
address@hidden declarations of @code{malloc} and
address@hidden put these declarations in configuration files
-specific to those systems.
address@hidden string library functions
-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.
-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:
-strcpy   strncpy   strcat   strncat
-strlen   strcmp    strncmp
-strchr   strrchr
address@hidden 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
address@hidden and @code{rindex}; other systems use the names
address@hidden 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
address@hidden 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
address@hidden and @code{strrchr} throughout:
-#ifndef HAVE_STRCHR
-#define strchr index
-#define strrchr rindex
address@hidden scanf
+On Windows, @code{errno} is not set on failure.
address@hidden table
-char *strchr ();
-char *strrchr ();
address@hidden example
address@hidden itemize
address@hidden Gnulib
address@hidden://, 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.
address@hidden xmalloc, in Gnulib
address@hidden error messages, in Gnulib
address@hidden 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
+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
address@hidden 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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]