1 This is ../info/standards.info, produced by makeinfo version 4.0 from
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999 Free Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
20 Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
26 File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
31 Last updated June 24, 1999.
35 * Preface:: About the GNU Coding Standards
36 * Legal Issues:: Keeping Free Software Free
37 * Design Advice:: General Program Design
38 * Program Behavior:: Program Behavior for All Programs
39 * Writing C:: Making The Best Use of C
40 * Documentation:: Documenting Programs
41 * Managing Releases:: The Release Process
42 * References:: References to Non-Free Software or Documentation
45 File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
47 About the GNU Coding Standards
48 ******************************
50 The GNU Coding Standards were written by Richard Stallman and other
51 GNU Project volunteers. Their purpose is to make the GNU system clean,
52 consistent, and easy to install. This document can also be read as a
53 guide to writing portable, robust and reliable programs. It focuses on
54 programs written in C, but many of the rules and principles are useful
55 even if you write in another programming language. The rules often
56 state reasons for writing in a certain way.
58 Corrections or suggestions for this document should be sent to
59 <gnu@gnu.org>. If you make a suggestion, please include a suggested
60 new wording for it; our time is limited. We prefer a context diff to
61 the `standards.texi' or `make-stds.texi' files, but if you don't have
62 those files, please mail your suggestion anyway.
64 This release of the GNU Coding Standards was last updated June 24,
68 File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
70 Keeping Free Software Free
71 **************************
73 This node discusses how you can make sure that GNU software remains
78 * Reading Non-Free Code:: Referring to Proprietary Programs
79 * Contributions:: Accepting Contributions
82 File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
84 Referring to Proprietary Programs
85 =================================
87 Don't in any circumstances refer to Unix source code for or during
88 your work on GNU! (Or to any other proprietary programs.)
90 If you have a vague recollection of the internals of a Unix program,
91 this does not absolutely mean you can't write an imitation of it, but
92 do try to organize the imitation internally along different lines,
93 because this is likely to make the details of the Unix version
94 irrelevant and dissimilar to your results.
96 For example, Unix utilities were generally optimized to minimize
97 memory use; if you go for speed instead, your program will be very
98 different. You could keep the entire input file in core and scan it
99 there instead of using stdio. Use a smarter algorithm discovered more
100 recently than the Unix program. Eliminate use of temporary files. Do
101 it in one pass instead of two (we did this in the assembler).
103 Or, on the contrary, emphasize simplicity instead of speed. For some
104 applications, the speed of today's computers makes simpler algorithms
107 Or go for generality. For example, Unix programs often have static
108 tables or fixed-size strings, which make for arbitrary limits; use
109 dynamic allocation instead. Make sure your program handles NULs and
110 other funny characters in the input files. Add a programming language
111 for extensibility and write part of the program in that language.
113 Or turn some parts of the program into independently usable
114 libraries. Or use a simple garbage collector instead of tracking
115 precisely when to free memory, or use a new GNU facility such as
119 File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Legal Issues
121 Accepting Contributions
122 =======================
124 If the program you are working on is copyrighted by the Free Software
125 Foundation, then when someone else sends you a piece of code to add to
126 the program, we need legal papers to use it--just as we asked you to
127 sign papers initially. _Each_ person who makes a nontrivial
128 contribution to a program must sign some sort of legal papers in order
129 for us to have clear title to the program; the main author alone is not
132 So, before adding in any contributions from other people, please tell
133 us, so we can arrange to get the papers. Then wait until we tell you
134 that we have received the signed papers, before you actually use the
137 This applies both before you release the program and afterward. If
138 you receive diffs to fix a bug, and they make significant changes, we
139 need legal papers for that change.
141 This also applies to comments and documentation files. For copyright
142 law, comments and code are just text. Copyright applies to all kinds of
143 text, so we need legal papers for all kinds.
145 We know it is frustrating to ask for legal papers; it's frustrating
146 for us as well. But if you don't wait, you are going out on a limb--for
147 example, what if the contributor's employer won't sign a disclaimer?
148 You might have to take that code out again!
150 You don't need papers for changes of a few lines here or there, since
151 they are not significant for copyright purposes. Also, you don't need
152 papers if all you get from the suggestion is some ideas, not actual code
153 which you use. For example, if someone send you one implementation, but
154 you write a different implementation of the same idea, you don't need to
157 The very worst thing is if you forget to tell us about the other
158 contributor. We could be very embarrassed in court some day as a
161 We have more detailed advice for maintainers of programs; if you have
162 reached the stage of actually maintaining a program for GNU (whether
163 released or not), please ask us for a copy.
166 File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
168 General Program Design
169 **********************
171 This node discusses some of the issues you should take into account
172 when designing your program.
176 * Compatibility:: Compatibility with other implementations
177 * Using Extensions:: Using non-standard features
178 * ANSI C:: Using ANSI C features
179 * Source Language:: Using languages other than C
182 File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice
184 Compatibility with Other Implementations
185 ========================================
187 With occasional exceptions, utility programs and libraries for GNU
188 should be upward compatible with those in Berkeley Unix, and upward
189 compatible with ANSI C if ANSI C specifies their behavior, and upward
190 compatible with POSIX if POSIX specifies their behavior.
192 When these standards conflict, it is useful to offer compatibility
193 modes for each of them.
195 ANSI C and POSIX prohibit many kinds of extensions. Feel free to
196 make the extensions anyway, and include a `--ansi', `--posix', or
197 `--compatible' option to turn them off. However, if the extension has
198 a significant chance of breaking any real programs or scripts, then it
199 is not really upward compatible. Try to redesign its interface.
201 Many GNU programs suppress extensions that conflict with POSIX if the
202 environment variable `POSIXLY_CORRECT' is defined (even if it is
203 defined with a null value). Please make your program recognize this
204 variable if appropriate.
206 When a feature is used only by users (not by programs or command
207 files), and it is done poorly in Unix, feel free to replace it
208 completely with something totally different and better. (For example,
209 `vi' is replaced with Emacs.) But it is nice to offer a compatible
210 feature as well. (There is a free `vi' clone, so we offer it.)
212 Additional useful features not in Berkeley Unix are welcome.
215 File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice
217 Using Non-standard Features
218 ===========================
220 Many GNU facilities that already exist support a number of convenient
221 extensions over the comparable Unix facilities. Whether to use these
222 extensions in implementing your program is a difficult question.
224 On the one hand, using the extensions can make a cleaner program.
225 On the other hand, people will not be able to build the program unless
226 the other GNU tools are available. This might cause the program to
227 work on fewer kinds of machines.
229 With some extensions, it might be easy to provide both alternatives.
230 For example, you can define functions with a "keyword" `INLINE' and
231 define that as a macro to expand into either `inline' or nothing,
232 depending on the compiler.
234 In general, perhaps it is best not to use the extensions if you can
235 straightforwardly do without them, but to use the extensions if they
236 are a big improvement.
238 An exception to this rule are the large, established programs (such
239 as Emacs) which run on a great variety of systems. Such programs would
240 be broken by use of GNU extensions.
242 Another exception is for programs that are used as part of
243 compilation: anything that must be compiled with other compilers in
244 order to bootstrap the GNU compilation facilities. If these require
245 the GNU compiler, then no one can compile them without having them
246 installed already. That would be no good.
249 File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice
251 ANSI C and pre-ANSI C
252 =====================
254 Do not ever use the "trigraph" feature of ANSI C.
256 ANSI C is widespread enough now that it is ok to write new programs
257 that use ANSI C features (and therefore will not work in non-ANSI
258 compilers). And if a program is already written in ANSI C, there's no
259 need to convert it to support non-ANSI compilers.
261 If you don't know non-ANSI C, there's no need to learn it; just
264 However, it is easy to support non-ANSI compilers in most programs,
265 so you might still consider doing so when you write a program. And if a
266 program you are maintaining has such support, you should try to keep it
269 To support pre-ANSI C, instead of writing function definitions in
276 write the definition in pre-ANSI style like this,
283 and use a separate declaration to specify the argument prototype:
287 You need such a declaration anyway, in a header file, to get the
288 benefit of ANSI C prototypes in all the files where the function is
289 called. And once you have the declaration, you normally lose nothing
290 by writing the function definition in the pre-ANSI style.
292 This technique does not work for integer types narrower than `int'.
293 If you think of an argument as being of a type narrower than `int',
294 declare it as `int' instead.
296 There are a few special cases where this technique is hard to use.
297 For example, if a function argument needs to hold the system type
298 `dev_t', you run into trouble, because `dev_t' is shorter than `int' on
299 some machines; but you cannot use `int' instead, because `dev_t' is
300 wider than `int' on some machines. There is no type you can safely use
301 on all machines in a non-ANSI definition. The only way to support
302 non-ANSI C and pass such an argument is to check the width of `dev_t'
303 using Autoconf and choose the argument type accordingly. This may not
304 be worth the trouble.
307 File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice
309 Using Languages Other Than C
310 ============================
312 Using a language other than C is like using a non-standard feature:
313 it will cause trouble for users. Even if GCC supports the other
314 language, users may find it inconvenient to have to install the
315 compiler for that other language in order to build your program. For
316 example, if you write your program in C++, people will have to install
317 the C++ compiler in order to compile your program. Thus, it is better
320 But there are three situations when there is no disadvantage in using
323 * It is okay to use another language if your program contains an
324 interpreter for that language.
326 For example, if your program links with GUILE, it is ok to write
327 part of the program in Scheme or another language supported by
330 * It is okay to use another language in a tool specifically intended
331 for use with that language.
333 This is okay because the only people who want to build the tool
334 will be those who have installed the other language anyway.
336 * If an application is of interest to a narrow community, then
337 perhaps it's not important if the application is inconvenient to
340 C has one other advantage over C++ and other compiled languages: more
341 people know C, so more people will find it easy to read and modify the
342 program if it is written in C.
345 File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
347 Program Behavior for All Programs
348 *********************************
350 This node describes how to write robust software. It also describes
351 general standards for error messages, the command line interface, and
352 how libraries should behave.
356 * Semantics:: Writing robust programs
357 * Libraries:: Library behavior
358 * Errors:: Formatting error messages
359 * User Interfaces:: Standards for command line interfaces
360 * Option Table:: Table of long options.
361 * Memory Usage:: When and how to care about memory needs
364 File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
366 Writing Robust Programs
367 =======================
369 Avoid arbitrary limits on the length or number of _any_ data
370 structure, including file names, lines, files, and symbols, by
371 allocating all data structures dynamically. In most Unix utilities,
372 "long lines are silently truncated". This is not acceptable in a GNU
375 Utilities reading files should not drop NUL characters, or any other
376 nonprinting characters _including those with codes above 0177_. The
377 only sensible exceptions would be utilities specifically intended for
378 interface to certain types of terminals or printers that can't handle
379 those characters. Whenever possible, try to make programs work
380 properly with sequences of bytes that represent multibyte characters,
381 using encodings such as UTF-8 and others.
383 Check every system call for an error return, unless you know you
384 wish to ignore errors. Include the system error text (from `perror' or
385 equivalent) in _every_ error message resulting from a failing system
386 call, as well as the name of the file if any and the name of the
387 utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
389 Check every call to `malloc' or `realloc' to see if it returned
390 zero. Check `realloc' even if you are making the block smaller; in a
391 system that rounds block sizes to a power of 2, `realloc' may get a
392 different block if you ask for less space.
394 In Unix, `realloc' can destroy the storage block if it returns zero.
395 GNU `realloc' does not have this bug: if it fails, the original block
396 is unchanged. Feel free to assume the bug is fixed. If you wish to
397 run your program on Unix, and wish to avoid lossage in this case, you
398 can use the GNU `malloc'.
400 You must expect `free' to alter the contents of the block that was
401 freed. Anything you want to fetch from the block, you must fetch before
404 If `malloc' fails in a noninteractive program, make that a fatal
405 error. In an interactive program (one that reads commands from the
406 user), it is better to abort the command and return to the command
407 reader loop. This allows the user to kill other processes to free up
408 virtual memory, and then try the command again.
410 Use `getopt_long' to decode arguments, unless the argument syntax
411 makes this unreasonable.
413 When static storage is to be written in during program execution, use
414 explicit C code to initialize it. Reserve C initialized declarations
415 for data that will not be changed.
417 Try to avoid low-level interfaces to obscure Unix data structures
418 (such as file directories, utmp, or the layout of kernel memory), since
419 these are less likely to work compatibly. If you need to find all the
420 files in a directory, use `readdir' or some other high-level interface.
421 These are supported compatibly by GNU.
423 The preferred signal handling facilities are the BSD variant of
424 `signal', and the POSIX `sigaction' function; the alternative USG
425 `signal' interface is an inferior design.
427 Nowadays, using the POSIX signal functions may be the easiest way to
428 make a program portable. If you use `signal', then on GNU/Linux
429 systems running GNU libc version 1, you should include `bsd/signal.h'
430 instead of `signal.h', so as to get BSD behavior. It is up to you
431 whether to support systems where `signal' has only the USG behavior, or
434 In error checks that detect "impossible" conditions, just abort.
435 There is usually no point in printing any message. These checks
436 indicate the existence of bugs. Whoever wants to fix the bugs will have
437 to read the source code and run a debugger. So explain the problem with
438 comments in the source. The relevant data will be in variables, which
439 are easy to examine with the debugger, so there is no point moving them
442 Do not use a count of errors as the exit status for a program.
443 _That does not work_, because exit status values are limited to 8 bits
444 (0 through 255). A single run of the program might have 256 errors; if
445 you try to return 256 as the exit status, the parent process will see 0
446 as the status, and it will appear that the program succeeded.
448 If you make temporary files, check the `TMPDIR' environment
449 variable; if that variable is defined, use the specified directory
453 File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
458 Try to make library functions reentrant. If they need to do dynamic
459 storage allocation, at least try to avoid any nonreentrancy aside from
460 that of `malloc' itself.
462 Here are certain name conventions for libraries, to avoid name
465 Choose a name prefix for the library, more than two characters long.
466 All external function and variable names should start with this prefix.
467 In addition, there should only be one of these in any given library
468 member. This usually means putting each one in a separate source file.
470 An exception can be made when two external symbols are always used
471 together, so that no reasonable program could use one without the
472 other; then they can both go in the same file.
474 External symbols that are not documented entry points for the user
475 should have names beginning with `_'. They should also contain the
476 chosen name prefix for the library, to prevent collisions with other
477 libraries. These can go in the same files with user entry points if
480 Static functions and variables can be used as you like and need not
481 fit any naming convention.
484 File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
486 Formatting Error Messages
487 =========================
489 Error messages from compilers should look like this:
491 SOURCE-FILE-NAME:LINENO: MESSAGE
493 If you want to mention the column number, use this format:
495 SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
497 Line numbers should start from 1 at the beginning of the file, and
498 column numbers should start from 1 at the beginning of the line. (Both
499 of these conventions are chosen for compatibility.) Calculate column
500 numbers assuming that space and all ASCII printing characters have
501 equal width, and assuming tab stops every 8 columns.
503 Error messages from other noninteractive programs should look like
506 PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
508 when there is an appropriate source file, or like this:
512 when there is no relevant source file.
514 If you want to mention the column number, use this format:
516 PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
518 In an interactive program (one that is reading commands from a
519 terminal), it is better not to include the program name in an error
520 message. The place to indicate which program is running is in the
521 prompt or with the screen layout. (When the same program runs with
522 input from a source other than a terminal, it is not interactive and
523 would do best to print error messages using the noninteractive style.)
525 The string MESSAGE should not begin with a capital letter when it
526 follows a program name and/or file name. Also, it should not end with
529 Error messages from interactive programs, and other messages such as
530 usage messages, should start with a capital letter. But they should not
534 File: standards.info, Node: User Interfaces, Next: Option Table, Prev: Errors, Up: Program Behavior
536 Standards for Command Line Interfaces
537 =====================================
539 Please don't make the behavior of a utility depend on the name used
540 to invoke it. It is useful sometimes to make a link to a utility with
541 a different name, and that should not change what it does.
543 Instead, use a run time option or a compilation switch or both to
544 select among the alternate behaviors.
546 Likewise, please don't make the behavior of the program depend on the
547 type of output device it is used with. Device independence is an
548 important principle of the system's design; do not compromise it merely
549 to save someone from typing an option now and then. (Variation in error
550 message syntax when using a terminal is ok, because that is a side issue
551 that people do not depend on.)
553 If you think one behavior is most useful when the output is to a
554 terminal, and another is most useful when the output is a file or a
555 pipe, then it is usually best to make the default behavior the one that
556 is useful with output to a terminal, and have an option for the other
559 Compatibility requires certain programs to depend on the type of
560 output device. It would be disastrous if `ls' or `sh' did not do so in
561 the way all users expect. In some of these cases, we supplement the
562 program with a preferred alternate version that does not depend on the
563 output device type. For example, we provide a `dir' program much like
564 `ls' except that its default output format is always multi-column
567 It is a good idea to follow the POSIX guidelines for the
568 command-line options of a program. The easiest way to do this is to use
569 `getopt' to parse them. Note that the GNU version of `getopt' will
570 normally permit options anywhere among the arguments unless the special
571 argument `--' is used. This is not what POSIX specifies; it is a GNU
574 Please define long-named options that are equivalent to the
575 single-letter Unix-style options. We hope to make GNU more user
576 friendly this way. This is easy to do with the GNU function
579 One of the advantages of long-named options is that they can be
580 consistent from program to program. For example, users should be able
581 to expect the "verbose" option of any GNU program which has one, to be
582 spelled precisely `--verbose'. To achieve this uniformity, look at the
583 table of common long-option names when you choose the option names for
584 your program (*note Option Table::).
586 It is usually a good idea for file names given as ordinary arguments
587 to be input files only; any output files would be specified using
588 options (preferably `-o' or `--output'). Even if you allow an output
589 file name as an ordinary argument for compatibility, try to provide an
590 option as another way to specify it. This will lead to more consistency
591 among GNU utilities, and fewer idiosyncracies for users to remember.
593 All programs should support two standard options: `--version' and
597 This option should direct the program to print information about
598 its name, version, origin and legal status, all on standard
599 output, and then exit successfully. Other options and arguments
600 should be ignored once this is seen, and the program should not
601 perform its normal function.
603 The first line is meant to be easy for a program to parse; the
604 version number proper starts after the last space. In addition,
605 it contains the canonical name for this program, in this format:
609 The program's name should be a constant string; _don't_ compute it
610 from `argv[0]'. The idea is to state the standard or canonical
611 name for the program, not its file name. There are other ways to
612 find out the precise file name where a command is found in `PATH'.
614 If the program is a subsidiary part of a larger package, mention
615 the package name in parentheses, like this:
617 emacsserver (GNU Emacs) 19.30
619 If the package has a version number which is different from this
620 program's version number, you can mention the package version
621 number just before the close-parenthesis.
623 If you *need* to mention the version numbers of libraries which
624 are distributed separately from the package which contains this
625 program, you can do so by printing an additional line of version
626 info for each library you want to mention. Use the same format
627 for these lines as for the first line.
629 Please do not mention all of the libraries that the program uses
630 "just for completeness"--that would produce a lot of unhelpful
631 clutter. Please mention library version numbers only if you find
632 in practice that they are very important to you in debugging.
634 The following line, after the version number line or lines, should
635 be a copyright notice. If more than one copyright notice is
636 called for, put each on a separate line.
638 Next should follow a brief statement that the program is free
639 software, and that users are free to copy and change it on certain
640 conditions. If the program is covered by the GNU GPL, say so
641 here. Also mention that there is no warranty, to the extent
644 It is ok to finish the output with a list of the major authors of
645 the program, as a way of giving credit.
647 Here's an example of output that follows these rules:
650 Copyright (C) 1996 Free Software Foundation, Inc.
651 GNU Emacs comes with NO WARRANTY,
652 to the extent permitted by law.
653 You may redistribute copies of GNU Emacs
654 under the terms of the GNU General Public License.
655 For more information about these matters,
656 see the files named COPYING.
658 You should adapt this to your program, of course, filling in the
659 proper year, copyright holder, name of program, and the references
660 to distribution terms, and changing the rest of the wording as
663 This copyright notice only needs to mention the most recent year in
664 which changes were made--there's no need to list the years for
665 previous versions' changes. You don't have to mention the name of
666 the program in these notices, if that is inconvenient, since it
667 appeared in the first line.
670 This option should output brief documentation for how to invoke the
671 program, on standard output, then exit successfully. Other
672 options and arguments should be ignored once this is seen, and the
673 program should not perform its normal function.
675 Near the end of the `--help' option's output there should be a line
676 that says where to mail bug reports. It should have this format:
678 Report bugs to MAILING-ADDRESS.
681 File: standards.info, Node: Option Table, Next: Memory Usage, Prev: User Interfaces, Up: Program Behavior
683 Table of Long Options
684 =====================
686 Here is a table of long options used by GNU programs. It is surely
687 incomplete, but we aim to list all the options that a new program might
688 want to be compatible with. If you use names not already in the table,
689 please send <gnu@gnu.org> a list of them, with their meanings, so we
690 can update the table.
696 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
705 `-a' in `etags', `tee', `time'; `-r' in `tar'.
741 For server programs, run in the background.
759 `-b' in `cpio' and `diff'.
765 Used in `cpio' and `tar'.
768 `-b' in `head' and `tail'.
774 Used in various programs to make output shorter.
777 `-c' in `head', `split', and `tail'.
786 Used in various programs to specify the directory to use.
789 `-c' in `chgrp' and `chown'.
798 `-c' in `su'; `-x' in GDB.
807 `-Z' in `tar' and `shar'.
819 `-W copyleft' in `gawk'.
822 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
834 Used in `tar' and `cpio'.
846 `-d' in Make and `m4'; `-t' in Bison.
852 `-d' in Bison and `ctags'.
858 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
864 Specify an I/O device (special file name).
879 Specify the directory to use, in various programs. In `ls', it
880 means to show directories themselves rather than their contents.
881 In `rm' and `ln', it means to not treat links to directories
908 `environment-overrides'
948 `-i' in `cpio'; `-x' in `tar'.
960 `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
991 `-f' in `cp', `ln', `mv', and `rm'.
997 For server programs, run in the foreground; in other words, don't
998 do anything special to run the server in the background.
1001 Used in `ls', `time', and `ptx'.
1025 `-z' in `tar' and `shar'.
1031 `-h' in `objdump' and `recode'
1037 Used to ask for brief usage information.
1042 `hide-control-chars'
1052 `-I' in `ls'; `-x' in `recode'.
1060 `ignore-blank-lines'
1064 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1072 `ignore-indentation'
1081 `ignore-matching-lines'
1084 `ignore-space-change'
1091 `-i' in `etags'; `-I' in `m4'.
1100 `-i', `-l', and `-m' in Finger.
1112 `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
1131 `-k' in `du' and `ls'.
1146 Used in `split', `head', and `tail'.
1156 `-t' in `cpio'; `-l' in `recode'.
1171 No listing of which programs already use this; someone should
1172 check to see if any actually do, and tell <gnu@gnu.org>.
1178 `-m' in `hello' and `uname'.
1217 `-m' in `install', `mkdir', and `mkfifo'.
1240 `no-character-count'
1298 Used in `emacsclient'.
1301 Used in various programs to inhibit warnings.
1328 `-n' in `cpio' and `ls'.
1340 `-l' in `tar', `cp', and `du'.
1352 `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1355 In various programs, specify the output file name.
1376 `-p' in `mkdir' and `rmdir'.
1388 `-c' in `cpio' and `tar'.
1400 Used in `tar' and `cp'.
1402 `preserve-environment'
1405 `preserve-modification-time'
1411 `preserve-permissions'
1439 Specify an HTTP proxy.
1448 Used in many programs to inhibit the usual output. *Note:* every
1449 program accepting `--quiet' should accept `--silent' as a synonym.
1476 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1485 `-r' in `tac' and `etags'.
1502 `report-identical-files'
1509 `-r' in `ls' and `nm'.
1539 Used by `recode' to chose files or pipes for sequencing passes.
1553 `show-function-line'
1560 Used in many programs to inhibit the usual output. *Note:* every
1561 program accepting `--silent' should accept `--quiet' as a synonym.
1567 Specify a file descriptor for a network server to use for its
1568 socket, instead of opening and binding a new socket. This
1569 provides a way to run, in a nonpriveledged process, a server that
1570 normally needs a reserved port number.
1576 `-W source' in `gawk'.
1600 Used in `tar' and `diff' to specify which file within a directory
1601 to start processing with.
1628 `-S' in `cp', `ln', `mv'.
1643 Used in GDB and `objdump'.
1652 `-t' in `expand' and `unexpand'.
1658 `-T' in `tput' and `ul'. `-t' in `wdiff'.
1667 Used in `ls' and `touch'.
1670 Specify how long to wait before giving up on some operation.
1679 `-t' in Make, `ranlib', and `recode'.
1685 `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
1713 `-u' in `cp', `ctags', `mv', `tar'.
1716 Used in `gawk'; same as `--help'.
1725 Print more information about progress. Many programs support this.
1731 Print the version number.
1734 `-V' in `cp', `ln', `mv'.
1749 `-w' in `ls' and `ptx'.
1761 File: standards.info, Node: Memory Usage, Prev: Option Table, Up: Program Behavior
1766 If it typically uses just a few meg of memory, don't bother making
1767 any effort to reduce memory usage. For example, if it is impractical
1768 for other reasons to operate on files more than a few meg long, it is
1769 reasonable to read entire input files into core to operate on them.
1771 However, for programs such as `cat' or `tail', that can usefully
1772 operate on very large files, it is important to avoid using a technique
1773 that would artificially limit the size of files it can handle. If a
1774 program works by lines and could be applied to arbitrary user-supplied
1775 input files, it should keep only a line in memory, because this is not
1776 very hard and users will want to be able to operate on input files that
1777 are bigger than will fit in core all at once.
1779 If your program creates complicated data structures, just make them
1780 in core and give a fatal error if `malloc' returns zero.
1783 File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
1785 Making The Best Use of C
1786 ************************
1788 This node provides advice on how best to use the C language when
1789 writing GNU software.
1793 * Formatting:: Formatting Your Source Code
1794 * Comments:: Commenting Your Work
1795 * Syntactic Conventions:: Clean Use of C Constructs
1796 * Names:: Naming Variables and Functions
1797 * System Portability:: Portability between different operating systems
1798 * CPU Portability:: Supporting the range of CPU types
1799 * System Functions:: Portability and ``standard'' library functions
1800 * Internationalization:: Techniques for internationalization
1801 * Mmap:: How you can safely use `mmap'.
1804 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
1806 Formatting Your Source Code
1807 ===========================
1809 It is important to put the open-brace that starts the body of a C
1810 function in column zero, and avoid putting any other open-brace or
1811 open-parenthesis or open-bracket in column zero. Several tools look
1812 for open-braces in column zero to find the beginnings of C functions.
1813 These tools will not work on code not formatted that way.
1815 It is also important for function definitions to start the name of
1816 the function in column zero. This helps people to search for function
1817 definitions, and may also help certain tools recognize them. Thus, the
1818 proper format is this:
1821 concat (s1, s2) /* Name starts in column zero here */
1823 { /* Open brace in column zero here */
1827 or, if you want to use ANSI C, format the definition like this:
1830 concat (char *s1, char *s2)
1835 In ANSI C, if the arguments don't fit nicely on one line, split it
1839 lots_of_args (int an_integer, long a_long, short a_short,
1840 double a_double, float a_float)
1843 For the body of the function, we prefer code formatted like this:
1854 return ++x + bar ();
1857 We find it easier to read a program when it has spaces before the
1858 open-parentheses and after the commas. Especially after the commas.
1860 When you split an expression into multiple lines, split it before an
1861 operator, not after one. Here is the right way:
1863 if (foo_this_is_long && bar > win (x, y, z)
1864 && remaining_condition)
1866 Try to avoid having two operators of different precedence at the same
1867 level of indentation. For example, don't write this:
1869 mode = (inmode[j] == VOIDmode
1870 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
1871 ? outmode[j] : inmode[j]);
1873 Instead, use extra parentheses so that the indentation shows the
1876 mode = ((inmode[j] == VOIDmode
1877 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
1878 ? outmode[j] : inmode[j]);
1880 Insert extra parentheses so that Emacs will indent the code properly.
1881 For example, the following indentation looks nice if you do it by hand,
1882 but Emacs would mess it up:
1884 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1885 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
1887 But adding a set of parentheses solves the problem:
1889 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1890 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
1892 Format do-while statements like this:
1900 Please use formfeed characters (control-L) to divide the program into
1901 pages at logical places (but not within a function). It does not matter
1902 just how long the pages are, since they do not have to fit on a printed
1903 page. The formfeeds should appear alone on lines by themselves.