standards.texi

autoconf是一个产生可以自动配置源代码包

@item recursive
Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
and @code{rm}.

@item reference-limit
Used in @code{makeinfo}.

@item references
@samp{-r} in @code{ptx}.

@item regex
@samp{-r} in @code{tac} and @code{etags}.

@item release
@samp{-r} in @code{uname}.

@item reload-state
@samp{-R} in @code{m4}.

@item relocation
@samp{-r} in @code{objdump}.

@item rename
@samp{-r} in @code{cpio}.

@item replace
@samp{-i} in @code{xargs}.

@item report-identical-files
@samp{-s} in @code{diff}.

@item reset-access-time
@samp{-a} in @code{cpio}.

@item reverse
@samp{-r} in @code{ls} and @code{nm}.

@item reversed-ed
@samp{-f} in @code{diff}.

@item right-side-defs
@samp{-R} in @code{ptx}.

@item same-order
@samp{-s} in @code{tar}.

@item same-permissions
@samp{-p} in @code{tar}.

@item save
@samp{-g} in @code{stty}.

@item se
Used in GDB.

@item sentence-regexp
@samp{-S} in @code{ptx}.

@item separate-dirs
@samp{-S} in @code{du}.

@item separator
@samp{-s} in @code{tac}.

@item sequence
Used by @code{recode} to chose files or pipes for sequencing passes.

@item shell
@samp{-s} in @code{su}.

@item show-all
@samp{-A} in @code{cat}.

@item show-c-function
@samp{-p} in @code{diff}.

@item show-ends
@samp{-E} in @code{cat}.

@item show-function-line
@samp{-F} in @code{diff}.

@item show-tabs
@samp{-T} in @code{cat}.

@item silent
Used in many programs to inhibit the usual output.
Every program accepting
@samp{--silent} should accept @samp{--quiet} as a synonym.

@item size
@samp{-s} in @code{ls}.

@item socket
Specify a file descriptor for a network server to use for its socket,
instead of opening and binding a new socket.  This provides a way to
run, in a nonpriveledged process, a server that normally needs a
reserved port number.

@item sort
Used in @code{ls}.

@item source
@samp{-W source} in @code{gawk}.

@item sparse
@samp{-S} in @code{tar}.

@item speed-large-files
@samp{-H} in @code{diff}.

@item split-at
@samp{-E} in @code{unshar}.

@item split-size-limit
@samp{-L} in @code{shar}.

@item squeeze-blank
@samp{-s} in @code{cat}.

@item start-delete
@samp{-w} in @code{wdiff}.

@item start-insert
@samp{-y} in @code{wdiff}.

@item starting-file
Used in @code{tar} and @code{diff} to specify which file within
a directory to start processing with.

@item statistics
@samp{-s} in @code{wdiff}.

@item stdin-file-list
@samp{-S} in @code{shar}.

@item stop
@samp{-S} in Make.

@item strict
@samp{-s} in @code{recode}.

@item strip
@samp{-s} in @code{install}.

@item strip-all
@samp{-s} in @code{strip}.

@item strip-debug
@samp{-S} in @code{strip}.

@item submitter
@samp{-s} in @code{shar}.

@item suffix
@samp{-S} in @code{cp}, @code{ln}, @code{mv}.

@item suffix-format
@samp{-b} in @code{csplit}.

@item sum
@samp{-s} in @code{gprof}.

@item summarize
@samp{-s} in @code{du}.

@item symbolic
@samp{-s} in @code{ln}.

@item symbols
Used in GDB and @code{objdump}.

@item synclines
@samp{-s} in @code{m4}.

@item sysname
@samp{-s} in @code{uname}.

@item tabs
@samp{-t} in @code{expand} and @code{unexpand}.

@item tabsize
@samp{-T} in @code{ls}.

@item terminal
@samp{-T} in @code{tput} and @code{ul}.
@samp{-t} in @code{wdiff}.

@item text
@samp{-a} in @code{diff}.

@item text-files
@samp{-T} in @code{shar}.

@item time
Used in @code{ls} and @code{touch}.

@item timeout
Specify how long to wait before giving up on some operation.

@item to-stdout
@samp{-O} in @code{tar}.

@item total
@samp{-c} in @code{du}.

@item touch
@samp{-t} in Make, @code{ranlib}, and @code{recode}.

@item trace
@samp{-t} in @code{m4}.

@item traditional
@samp{-t} in @code{hello};
@samp{-W traditional} in @code{gawk};
@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.

@item tty
Used in GDB.

@item typedefs
@samp{-t} in @code{ctags}.

@item typedefs-and-c++
@samp{-T} in @code{ctags}.

@item typeset-mode
@samp{-t} in @code{ptx}.

@item uncompress
@samp{-z} in @code{tar}.

@item unconditional
@samp{-u} in @code{cpio}.

@item undefine
@samp{-U} in @code{m4}.

@item undefined-only
@samp{-u} in @code{nm}.

@item update
@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.

@item usage
Used in @code{gawk}; same as @samp{--help}.

@item uuencode
@samp{-B} in @code{shar}.

@item vanilla-operation
@samp{-V} in @code{shar}.

@item verbose
Print more information about progress.  Many programs support this.

@item verify
@samp{-W} in @code{tar}.

@item version
Print the version number.

@item version-control
@samp{-V} in @code{cp}, @code{ln}, @code{mv}.

@item vgrind
@samp{-v} in @code{ctags}.

@item volume
@samp{-V} in @code{tar}.

@item what-if
@samp{-W} in Make.

@item whole-size-limit
@samp{-l} in @code{shar}.

@item width
@samp{-w} in @code{ls} and @code{ptx}.

@item word-regexp
@samp{-W} in @code{ptx}.

@item writable
@samp{-T} in @code{who}.

@item zeros
@samp{-z} in @code{gprof}.
@end table

@node Memory Usage
@section Memory Usage
@cindex memory usage

If a program typically uses just a few meg of memory, don't bother making any
effort to reduce memory usage.  For example, if it is impractical for
other reasons to operate on files more than a few meg long, it is
reasonable to read entire input files into core to operate on them.

However, for programs such as @code{cat} or @code{tail}, that can
usefully operate on very large files, it is important to avoid using a
technique that would artificially limit the size of files it can handle.
If a program works by lines and could be applied to arbitrary
user-supplied input files, it should keep only a line in memory, because
this is not very hard and users will want to be able to operate on input
files that are bigger than will fit in core all at once.

If your program creates complicated data structures, just make them in
core and give a fatal error if @code{malloc} returns zero.

@node File Usage
@section File Usage
@cindex file usage

Programs should be prepared to operate when @file{/usr} and @file{/etc}
are read-only file systems.  Thus, if the program manages log files,
lock files, backup files, score files, or any other files which are
modified for internal purposes, these files should not be stored in
@file{/usr} or @file{/etc}.

There are two exceptions.  @file{/etc} is used to store system
configuration information; it is reasonable for a program to modify
files in @file{/etc} when its job is to update the system configuration.
Also, if the user explicitly asks to modify one file in a directory, it
is reasonable for the program to store other files in the same
directory.

@node Writing C
@chapter Making The Best Use of C

This chapter provides advice on how best to use the C language
when writing GNU software.

@menu
* Formatting::                  Formatting Your Source Code
* Comments::                    Commenting Your Work
* Syntactic Conventions::       Clean Use of C Constructs
* Names::                       Naming Variables, Functions, and Files
* System Portability::          Portability between different operating systems
* CPU Portability::             Supporting the range of CPU types
* System Functions::            Portability and ``standard'' library functions
* Internationalization::        Techniques for internationalization
* Character Set::               Use ASCII by default.
* Quote Characters::            Use `...' in the C locale.
* Mmap::                        How you can safely use @code{mmap}.
@end menu

@node Formatting
@section Formatting Your Source Code
@cindex formatting source code

@cindex open brace
@cindex braces, in C source
It is important to put the open-brace that starts the body of a C
function in column one, and avoid putting any other open-brace or
open-parenthesis or open-bracket in column one.  Several tools look
for open-braces in column one to find the beginnings of C functions.
These tools will not work on code not formatted that way.

It is also important for function definitions to start the name of the
function in column one.  This helps people to search for function
definitions, and may also help certain tools recognize them.  Thus,
using Standard C syntax, the format is this:

@example
static char *
concat (char *s1, char *s2)
@{
  @dots{}
@}
@end example

@noindent
or, if you want to use traditional C syntax, format the definition like
this:

@example
static char *
concat (s1, s2)        /* Name starts in column one here */
     char *s1, *s2;
@{                     /* Open brace in column one here */
  @dots{}
@}
@end example

In Standard C, if the arguments don't fit nicely on one line,
split it like this:

@example
int
lots_of_args (int an_integer, long a_long, short a_short,
              double a_double, float a_float)
@dots{}
@end example

The rest of this section gives our recommendations for other aspects of
C formatting style, which is also the default style of the @code{indent}
program in version 1.2 and newer.  It corresponds to the options

@smallexample
-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
@end smallexample

We don't think of these recommendations 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))
  haha = bar[4] + 5;
else
  @{
    while (z)
      @{
        haha += foo (z, z);
        z--;
      @}
    return ++x + bar ();
  @}
@end example

@cindex spaces before open-paren
We find it easier to read a program when it has spaces before the
open-parentheses and after the commas.  Especially after the commas.

When you split an expression into multiple lines, split it
before an operator, not after one.  Here is the right way:

@cindex expressions, splitting
@example
if (foo_this_is_long && bar > win (x, y, z)
    && remaining_condition)
@end example

Try to avoid having two operators of different precedence at the same
level of indentation.  For example, don't write this:

@example
mode = (inmode[j] == VOIDmode
        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
        ? outmode[j] : inmode[j]);
@end example

Instead, use extra parentheses so that the indentation shows the nesting:

@example
mode = ((inmode[j] == VOIDmode
         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
        ? outmo