From: Akim Demaille Date: Thu, 27 Apr 2000 17:28:54 +0000 (+0000) Subject: Update foreign files. X-Git-Tag: autoconf-2.50~959 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3e52e5bc238b17e19813d2c6d0b08df87f95faf2;p=thirdparty%2Fautoconf.git Update foreign files. --- diff --git a/config.guess b/config.guess index 20c971aae..10c05d23b 100755 --- a/config.guess +++ b/config.guess @@ -266,7 +266,7 @@ EOF exit 0 ;; # The situation for MiNT is a little confusing. The machine name # can be virtually everything (everything which is not - # "atarist" or "atariste" at least should have a processor + # "atarist" or "atariste" at least should have a processor # > m68000). The system name ranges from "MiNT" over "FreeMiNT" # to the lowercase version "mint" (or "freemint"). Finally # the system name "TOS" denotes a system which is actually not @@ -360,7 +360,7 @@ EOF AViiON:dgux:*:*) # DG/UX returns AViiON for all architectures UNAME_PROCESSOR=`/usr/bin/uname -p` - if [ $UNAME_PROCESSOR = mc88100 ] || [ $UNAME_PROCESSOR = mc88110] + if [ $UNAME_PROCESSOR = mc88100 ] || [ $UNAME_PROCESSOR = mc88110 ] then if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx ] || \ [ ${TARGET_BINARY_INTERFACE}x = x ] @@ -458,6 +458,8 @@ EOF 9000/[34]?? ) HP_ARCH=m68k ;; 9000/[678][0-9][0-9]) sed 's/^ //' << EOF >$dummy.c + + #define _HPUX_SOURCE #include #include @@ -588,7 +590,7 @@ EOF echo alpha-cray-unicosmk${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit 0 ;; CRAY*SV1:*:*:*) - echo sv1-cray-unicos${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' + echo sv1-cray-unicos${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit 0 ;; CRAY-2:*:*:*) echo cray2-cray-unicos @@ -604,7 +606,7 @@ EOF hp300:OpenBSD:*:*) echo m68k-unknown-openbsd${UNAME_RELEASE} exit 0 ;; - i?86:BSD/386:*:* | i?86:BSD/OS:*:*) + i?86:BSD/386:*:* | i?86:BSD/OS:*:* | *:Ascend\ Embedded/OS:*:*) echo ${UNAME_MACHINE}-pc-bsdi${UNAME_RELEASE} exit 0 ;; sparc*:BSD/OS:*:*) @@ -614,12 +616,6 @@ EOF echo ${UNAME_MACHINE}-unknown-bsdi${UNAME_RELEASE} exit 0 ;; *:FreeBSD:*:*) - if test -x /usr/bin/objformat; then - if test "elf" = "`/usr/bin/objformat`"; then - echo ${UNAME_MACHINE}-unknown-freebsdelf`echo ${UNAME_RELEASE}|sed -e 's/[-_].*//'` - exit 0 - fi - fi echo ${UNAME_MACHINE}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` exit 0 ;; *:OpenBSD:*:*) @@ -670,6 +666,10 @@ EOF echo "${UNAME_MACHINE}-pc-linux-gnuaout" exit 0 ;; + elf_i?86) + echo "${UNAME_MACHINE}-pc-linux" + exit 0 + ;; i?86coff) echo "${UNAME_MACHINE}-pc-linux-gnucoff" exit 0 @@ -721,7 +721,7 @@ EOF if test "$?" = 0 ; then LIBC="libc1" fi - fi + fi rm -f $dummy.c $dummy echo powerpc-unknown-linux-gnu${LIBC} exit 0 @@ -1024,8 +1024,23 @@ EOF *:Mac*OS:*:*) echo ${UNAME_MACHINE}-apple-macos${UNAME_RELEASE} exit 0 ;; + *:Darwin:*:*) + echo `uname -p`-apple-darwin${UNAME_RELEASE} + exit 0 ;; + *:procnto*:*:* | *:QNX:[0123456789]*:*) + if test "${UNAME_MACHINE}" = "x86pc"; then + UNAME_MACHINE=pc + fi + echo `uname -p`-${UNAME_MACHINE}-nto-qnx + exit 0 ;; *:QNX:*:4*) - echo i386-qnx-qnx${UNAME_VERSION} + echo i386-pc-qnx + exit 0 ;; + NSR-W:NONSTOP_KERNEL:*:*) + echo nsr-tandem-nsk${UNAME_RELEASE} + exit 0 ;; + BS2000:POSIX*:*:*) + echo bs2000-siemens-sysv exit 0 ;; esac diff --git a/config.sub b/config.sub index 00b90f884..e8b7be4cd 100755 --- a/config.sub +++ b/config.sub @@ -73,7 +73,7 @@ esac # Here we must recognize all the valid KERNEL-OS combinations. maybe_os=`echo $1 | sed 's/^\(.*\)-\([^-]*-[^-]*\)$/\2/'` case $maybe_os in - linux-gnu*) + nto-qnx* | linux-gnu*) os=-$maybe_os basic_machine=`echo $1 | sed 's/^\(.*\)-\([^-]*-[^-]*\)$/\1/'` ;; @@ -174,6 +174,7 @@ case $basic_machine in tahoe | i860 | ia64 | m32r | m68k | m68000 | m88k | ns32k | arc | arm \ | arme[lb] | pyramid | mn10200 | mn10300 | tron | a29k \ | 580 | i960 | h8300 \ + | x86 | ppcbe | mipsbe | mipsle | shbe | shle | armbe | armle \ | hppa | hppa1.0 | hppa1.1 | hppa2.0 | hppa2.0w | hppa2.0n \ | alpha | alphaev[4-8] | alphaev56 | alphapca5[67] \ | alphaev6[78] \ @@ -207,6 +208,7 @@ case $basic_machine in | mips-* | pyramid-* | tron-* | a29k-* | romp-* | rs6000-* \ | power-* | none-* | 580-* | cray2-* | h8300-* | h8500-* | i960-* \ | xmp-* | ymp-* \ + | x86-* | ppcbe-* | mipsbe-* | mipsle-* | shbe-* | shle-* | armbe-* | armle-* \ | hppa-* | hppa1.0-* | hppa1.1-* | hppa2.0-* | hppa2.0w-* | hppa2.0n-* \ | alpha-* | alphaev[4-8]-* | alphaev56-* | alphapca5[67]-* \ | alphaev6[78]-* \ @@ -471,9 +473,6 @@ case $basic_machine in basic_machine=i386-unknown os=-mingw32 ;; - i386-qnx | qnx) - basic_machine=i386-qnx - ;; iris | iris4d) basic_machine=mips-sgi case $os in @@ -596,6 +595,9 @@ case $basic_machine in np1) basic_machine=np1-gould ;; + nsr-tandem) + basic_machine=nsr-tandem + ;; op50n-* | op60c-*) basic_machine=hppa1.1-oki os=-proelf @@ -933,9 +935,22 @@ case $os in | -udi* | -eabi* | -lites* | -ieee* | -go32* | -aux* \ | -cygwin* | -pe* | -psos* | -moss* | -proelf* | -rtems* \ | -mingw32* | -linux-gnu* | -uxpv* | -beos* | -mpeix* | -udk* \ - | -interix* | -uwin* | -rhapsody* | -opened* | -openstep* | -oskit*) + | -interix* | -uwin* | -rhapsody* | -darwin* | -opened* \ + | -openstep* | -oskit*) # Remember, each alternative MUST END IN *, to match a version number. ;; + -qnx*) + case $basic_machine in + x86-* | i[34567]86-*) + ;; + *) + os=-nto$os + ;; + esac + ;; + -nto*) + os=-nto-qnx + ;; -sim | -es1800* | -hms* | -xray | -os68k* | -none* | -v88r* \ | -windows* | -osx | -abug | -netware* | -os9* | -beos* \ | -macos* | -mpw* | -magic* | -mmixware* | -mon960* | -lnews*) @@ -982,6 +997,9 @@ case $os in -ns2 ) os=-nextstep2 ;; + -nsk) + os=-nsk + ;; # Preserve the version number of sinix5. -sinix5.*) os=`echo $os | sed -e 's|sinix|sysv|'` @@ -995,9 +1013,6 @@ case $os in -oss*) os=-sysv3 ;; - -qnx) - os=-qnx4 - ;; -svr4) os=-sysv4 ;; @@ -1022,9 +1037,6 @@ case $os in -*mint | -*MiNT) os=-mint ;; - -neutrino* | -nto*) - os=-neutrino - ;; -none) ;; *) @@ -1245,9 +1257,6 @@ case $basic_machine in -*mint | -*MiNT) vendor=atari ;; - -neutrino* | -nto*) - vendor=qnx - ;; esac basic_machine=`echo $basic_machine | sed "s/unknown/$vendor/"` ;; diff --git a/doc/make-stds.texi b/doc/make-stds.texi index 41fb2123f..637dfbe19 100644 --- a/doc/make-stds.texi +++ b/doc/make-stds.texi @@ -21,6 +21,8 @@ chapter @end ifclear @end iftex describes conventions for writing the Makefiles for GNU programs. +Using Automake will help you write a Makefile that follows these +conventions. @menu * Makefile Basics:: General Conventions for Makefiles @@ -79,7 +81,7 @@ foo.1 : foo.man sedscript @noindent will fail when the build directory is not the source directory, because -@file{foo.man} and @file{sedscript} are in the the source directory. +@file{foo.man} and @file{sedscript} are in the source directory. When using GNU @code{make}, relying on @samp{VPATH} to find the source file will work in the case where there is a single dependency file, @@ -257,6 +259,18 @@ $(INSTALL_PROGRAM) foo $(bindir)/foo $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a @end example +Optionally, you may prepend the value of @code{DESTDIR} to the target +filename. Doing this allows the installer to create a snapshot of the +installation to be copied onto the real target filesystem later. Do not +set the value of @code{DESTDIR} in your Makefile, and do not include it +in any installed files. With support for @code{DESTDIR}, the above +examples become: + +@example +$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo +$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a +@end example + @noindent Always use a file name, not a directory name, as the second argument of the installation commands. Use a separate command for each file to be @@ -283,6 +297,10 @@ When building the complete GNU system, the prefix will be empty and @file{/usr} will be a symbolic link to @file{/}. (If you are using Autoconf, write it as @samp{@@prefix@@}.) +Running @samp{make install} with a different value of @code{prefix} +from the one used to build the program should @var{not} recompile +the program. + @item exec_prefix A prefix used in constructing the default values of some of the variables listed below. The default value of @code{exec_prefix} should @@ -292,6 +310,10 @@ be @code{$(prefix)}. Generally, @code{$(exec_prefix)} is used for directories that contain machine-specific files (such as executables and subroutine libraries), while @code{$(prefix)} is used directly for other directories. + +Running @samp{make install} with a different value of @code{exec_prefix} +from the one used to build the program should @var{not} recompile the +program. @end table Executable programs are installed in one of the following directories. @@ -568,12 +590,12 @@ Here is a sample rule to install an Info file: @comment This example has been carefully formatted for the Make manual. @comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. @smallexample -$(infodir)/foo.info: foo.info +$(DESTDIR)$(infodir)/foo.info: foo.info $(POST_INSTALL) # There may be a newer info file in . than in srcdir. -if test -f foo.info; then d=.; \ else d=$(srcdir); fi; \ - $(INSTALL_DATA) $$d/foo.info $@@; \ + $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ # Run install-info only if it exists. # Use `if' instead of just prepending `-' to the # line so we notice real errors from install-info. @@ -581,8 +603,8 @@ $(infodir)/foo.info: foo.info # fail gracefully when there is an unknown command. if $(SHELL) -c 'install-info --version' \ >/dev/null 2>&1; then \ - install-info --dir-file=$(infodir)/dir \ - $(infodir)/foo.info; \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir \ + $(DESTDIR)$(infodir)/foo.info; \ else true; fi @end smallexample @@ -725,7 +747,7 @@ The easiest way to do this is to create a subdirectory appropriately named, use @code{ln} or @code{cp} to install the proper files in it, and then @code{tar} that subdirectory. -Compress the tar file file with @code{gzip}. For example, the actual +Compress the tar file with @code{gzip}. For example, the actual distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. The @code{dist} target should explicitly depend on all non-source files diff --git a/doc/standards.texi b/doc/standards.texi index 6d9778dec..30db4d862 100644 --- 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 March 26, 1999 +@set lastupdate March 2, 2000 @c %**end of header @ifinfo @@ -118,11 +118,12 @@ This release of the GNU Coding Standards was last updated @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 @@ -158,7 +159,6 @@ Or turn some parts of the program into independently usable libraries. 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 @@ -203,37 +203,111 @@ We have more detailed advice for maintainers of programs; if you have 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 @@ -246,7 +320,8 @@ completely with something totally different and better. (For example, @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 @@ -270,36 +345,28 @@ straightforwardly do without them, but to use the extensions if they 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 @@ -308,7 +375,7 @@ foo (int x, int y) @end example @noindent -write the definition in pre-@sc{ansi} style like this, +write the definition in pre-standard style like this, @example int @@ -325,9 +392,9 @@ int foo (int, 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}, @@ -338,54 +405,29 @@ example, if a function argument needs to hold the system type @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 @@ -522,6 +564,20 @@ Error messages from compilers should look like this: @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 @@ -538,6 +594,12 @@ when there is an appropriate source file, or like this: @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 @@ -1084,6 +1146,9 @@ Used to ask for brief usage information. @item hide-control-chars @samp{-q} in @code{ls}. +@item html +In @code{makeinfo}, output HTML. + @item idle @samp{-u} in @code{who}. @@ -1144,6 +1209,10 @@ Used to ask for brief usage information. @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}. @@ -1397,6 +1466,10 @@ Used in GDB. @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. @@ -1870,7 +1943,8 @@ concat (s1, s2) /* Name starts in column zero here */ @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 * @@ -1880,7 +1954,7 @@ concat (char *s1, char *s2) @} @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 @@ -1890,7 +1964,17 @@ lots_of_args (int an_integer, long a_long, short a_short, @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)) @@ -1936,14 +2020,15 @@ mode = ((inmode[j] == VOIDmode 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 @@ -1965,7 +2050,6 @@ pages at logical places (but not within a function). It does not matter 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 @@ -2064,6 +2148,13 @@ but, by contrast, write the comments this way for a @samp{#ifndef}: 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 @@ -2259,14 +2350,22 @@ Avoid using the format of semi-internal data bases (e.g., directories) 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 @@ -2292,9 +2391,9 @@ while ((c = getchar()) != EOF) 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 @@ -2313,32 +2412,40 @@ error (s, a1, a2, a3) @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 @@ -2360,7 +2467,7 @@ actual conflicts. @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 @@ -2392,7 +2499,7 @@ 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 @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: @@ -2422,7 +2529,7 @@ 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 @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