X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fstandards.info-1;fp=info%2Fstandards.info-1;h=0000000000000000000000000000000000000000;hb=a5812bf2ff9a9cf40f4ff78dcb83f5b4c295bd18;hp=4ffe0231dfe8b2cbf76c63552421f2f0f51a77d3;hpb=ccce6217f84987dff10ed3d2b60b9f0f65d8f25a;p=chise%2Fxemacs-chise.git.1 diff --git a/info/standards.info-1 b/info/standards.info-1 deleted file mode 100644 index 4ffe023..0000000 --- a/info/standards.info-1 +++ /dev/null @@ -1,1973 +0,0 @@ -This is Info file ../info/standards.info, produced by Makeinfo version -1.68 from the input file standards.texi. - -START-INFO-DIR-ENTRY -* Standards: (standards). GNU coding standards. -END-INFO-DIR-ENTRY - - GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free -Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. - - -File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) - -Version -******* - - Last updated 17 May 1996. - -* Menu: - -* Preface:: About the GNU Coding Standards -* Intellectual Property:: Keeping Free Software Free -* Design Advice:: General Program Design -* Program Behavior:: Program Behavior for All Programs -* Writing C:: Making The Best Use of C -* Documentation:: Documenting Programs -* Managing Releases:: The Release Process - - -File: standards.info, Node: Preface, Next: Intellectual Property, Prev: Top, Up: Top - -About the GNU Coding Standards -****************************** - - The GNU Coding Standards were written by Richard Stallman and other -GNU Project volunteers. Their purpose is to make the GNU system clean, -consistent, and easy to install. This document can also be read as a -guide to writing portable, robust and reliable programs. It focuses on -programs written in C, but many of the rules and principles are useful -even if you write in another programming language. The rules often -state reasons for writing in a certain way. - - Corrections or suggestions regarding this document should be sent to -`gnu@prep.ai.mit.edu'. If you make a suggestion, please include a -suggested new wording for it; our time is limited. We prefer a context -diff to the `standards.texi' or `make-stds.texi' files, but if you -don't have those files, please mail your suggestion anyway. - - This release of the GNU Coding Standards was last updated 17 May -1996. - - -File: standards.info, Node: Intellectual Property, Next: Design Advice, Prev: Preface, Up: Top - -Keeping Free Software Free -************************** - - This node discusses how you can make sure that GNU software remains -unencumbered. - -* Menu: - -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions - - -File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Intellectual Property - -Referring to Proprietary Programs -================================= - - Don't in any circumstances refer to Unix source code for or during -your work on GNU! (Or to any other proprietary programs.) - - If you have a vague recollection of the internals of a Unix program, -this does not absolutely mean you can't write an imitation of it, but -do try to organize the imitation internally along different lines, -because this is likely to make the details of the Unix version -irrelevant and dissimilar to your results. - - For example, Unix utilities were generally optimized to minimize -memory use; if you go for speed instead, your program will be very -different. You could keep the entire input file in core and scan it -there instead of using stdio. Use a smarter algorithm discovered more -recently than the Unix program. Eliminate use of temporary files. Do -it in one pass instead of two (we did this in the assembler). - - Or, on the contrary, emphasize simplicity instead of speed. For some -applications, the speed of today's computers makes simpler algorithms -adequate. - - Or go for generality. For example, Unix programs often have static -tables or fixed-size strings, which make for arbitrary limits; use -dynamic allocation instead. Make sure your program handles NULs and -other funny characters in the input files. Add a programming language -for extensibility and write part of the program in that language. - - 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. - - -File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Intellectual Property - -Accepting Contributions -======================= - - If someone else sends you a piece of code to add to the program you -are working on, we need legal papers to use it--the same sort of legal -papers we will need to get from you. *Each* significant contributor to -a program must sign some sort of legal papers in order for us to have -clear title to the program. The main author alone is not enough. - - So, before adding in any contributions from other people, tell us so -we can arrange to get the papers. Then wait until we tell you that we -have received the signed papers, before you actually use the -contribution. - - This applies both before you release the program and afterward. If -you receive diffs to fix a bug, and they make significant changes, we -need legal papers for it. - - You don't need papers for changes of a few lines here or there, since -they are not significant for copyright purposes. Also, you don't need -papers if all you get from the suggestion is some ideas, not actual code -which you use. For example, if you write a different solution to the -problem, you don't need to get papers. - - We know this is frustrating; it's frustrating for us as well. But if -you don't wait, you are going out on a limb--for example, what if the -contributor's employer won't sign a disclaimer? You might have to take -that code out again! - - The very worst thing is if you forget to tell us about the other -contributor. We could be very embarrassed in court some day as a -result. - - -File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Intellectual Property, Up: Top - -General Program Design -********************** - - This node discusses some of the issues you should take into account -when designing your program. - -* Menu: - -* Compatibility:: Compatibility with other implementations -* Using Extensions:: Using non-standard features -* ANSI C:: Using ANSI C features -* Source Language:: Using languages other than C - - -File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice - -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 ANSI C if ANSI C specifies their behavior, and upward -compatible with POSIX if POSIX specifies their behavior. - - When these standards conflict, it is useful to offer compatibility -modes for each of them. - - ANSI C and POSIX prohibit many kinds of extensions. Feel free to -make the extensions anyway, and include a `--ansi', `--posix', or -`--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. - - Many GNU programs suppress extensions that conflict with POSIX if the -environment variable `POSIXLY_CORRECT' is defined (even if it is -defined with a null value). Please make your program recognize this -variable if appropriate. - - When a feature is used only by users (not by programs or command -files), and it is done poorly in Unix, feel free to replace it -completely with something totally different and better. (For example, -`vi' is replaced with Emacs.) But it is nice to offer a compatible -feature as well. (There is a free `vi' clone, so we offer it.) - - Additional useful features not in Berkeley Unix are welcome. -Additional programs with no counterpart in Unix may be useful, but our -first priority is usually to duplicate what Unix already has. - - -File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice - -Using Non-standard Features -=========================== - - Many GNU facilities that already exist support a number of convenient -extensions over the comparable Unix facilities. Whether to use these -extensions in implementing your program is a difficult question. - - On the one hand, using the extensions can make a cleaner program. -On the other hand, people will not be able to build the program unless -the other GNU tools are available. This might cause the program to -work on fewer kinds of machines. - - With some extensions, it might be easy to provide both alternatives. -For example, you can define functions with a "keyword" `INLINE' and -define that as a macro to expand into either `inline' or nothing, -depending on the compiler. - - In general, perhaps it is best not to use the extensions if you can -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. - - -File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice - -ANSI C and pre-ANSI C -===================== - - Do not ever use the "trigraph" feature of ANSI C. - - ANSI C is widespread enough now that it is ok to write new programs -that use ANSI C features (and therefore will not work in non-ANSI -compilers). And if a program is already written in ANSI C, there's no -need to convert it to support non-ANSI compilers. - - However, it is easy to support non-ANSI compilers in most programs, -so you might still consider doing so when you write a program. Instead -of writing function definitions in ANSI prototype form, - - int - foo (int x, int y) - ... - -write the definition in pre-ANSI style like this, - - int - foo (x, y) - int x, y; - ... - -and use a separate declaration to specify the argument prototype: - - int foo (int, int); - - You need such a declaration anyway, in a header file, to get the -benefit of ANSI C prototypes in all the files where the function is -called. And once you have it, you lose nothing by writing the function -definition in the pre-ANSI style. - - If you don't know non-ANSI C, there's no need to learn it; just -write in ANSI C. - - -File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice - -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. So -please write in C. - - There are three exceptions for this rule: - - * It is okay to use a special language if the same 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. - - * It is okay to use another language in a tool specifically intended - for use with that language. - - This is okay because the only people who want to build the tool - will be those who have installed the other language anyway. - - * If an application is not of extremely widespread interest, then - perhaps it's not important if the application is inconvenient to - install. - - -File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top - -Program Behavior for All Programs -********************************* - - This node describes how to write robust software. It also describes -general standards for error messages, the command line interface, and -how libraries should behave. - -* Menu: - -* Semantics:: Writing robust programs -* Libraries:: Library behavior -* Errors:: Formatting error messages -* User Interfaces:: Standards for command line interfaces -* Memory Usage:: When and how to care about memory needs - - -File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior - -Writing Robust Programs -======================= - - Avoid arbitrary limits on the length or number of *any* data -structure, including file names, lines, files, and symbols, by -allocating all data structures dynamically. In most Unix utilities, -"long lines are silently truncated". This is not acceptable in a GNU -utility. - - Utilities reading files should not drop NUL characters, or any other -nonprinting characters *including those with codes above 0177*. The -only sensible exceptions would be utilities specifically intended for -interface to certain types of printers that can't handle those -characters. - - Check every system call for an error return, unless you know you -wish to ignore errors. Include the system error text (from `perror' or -equivalent) in *every* error message resulting from a failing system -call, as well as the name of the file if any and the name of the -utility. Just "cannot open foo.c" or "stat failed" is not sufficient. - - Check every call to `malloc' or `realloc' to see if it returned -zero. Check `realloc' even if you are making the block smaller; in a -system that rounds block sizes to a power of 2, `realloc' may get a -different block if you ask for less space. - - In Unix, `realloc' can destroy the storage block if it returns zero. -GNU `realloc' does not have this bug: if it fails, the original block -is unchanged. Feel free to assume the bug is fixed. If you wish to -run your program on Unix, and wish to avoid lossage in this case, you -can use the GNU `malloc'. - - You must expect `free' to alter the contents of the block that was -freed. Anything you want to fetch from the block, you must fetch before -calling `free'. - - If `malloc' fails in a noninteractive program, make that a fatal -error. In an interactive program (one that reads commands from the -user), it is better to abort the command and return to the command -reader loop. This allows the user to kill other processes to free up -virtual memory, and then try the command again. - - Use `getopt_long' to decode arguments, unless the argument syntax -makes this unreasonable. - - When static storage is to be written in during program execution, use -explicit C code to initialize it. Reserve C initialized declarations -for data that will not be changed. - - Try to avoid low-level interfaces to obscure Unix data structures -(such as file directories, utmp, or the layout of kernel memory), since -these are less likely to work compatibly. If you need to find all the -files in a directory, use `readdir' or some other high-level interface. -These will be supported compatibly by GNU. - - By default, the GNU system will provide the signal handling -functions of BSD and of POSIX. So GNU software should be written to use -these. - - In error checks that detect "impossible" conditions, just abort. -There is usually no point in printing any message. These checks -indicate the existence of bugs. Whoever wants to fix the bugs will have -to read the source code and run a debugger. So explain the problem with -comments in the source. The relevant data will be in variables, which -are easy to examine with the debugger, so there is no point moving them -elsewhere. - - Do not use a count of errors as the exit status for a program. -*That does not work*, because exit status values are limited to 8 bits -(0 through 255). A single run of the program might have 256 errors; if -you try to return 256 as the exit status, the parent process will see 0 -as the status, and it will appear that the program succeeded. - - If you make temporary files, check the `TMPDIR' environment -variable; if that variable is defined, use the specified directory -instead of `/tmp'. - - -File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior - -Library Behavior -================ - - Try to make library functions reentrant. If they need to do dynamic -storage allocation, at least try to avoid any nonreentrancy aside from -that of `malloc' itself. - - Here are certain name conventions for libraries, to avoid name -conflicts. - - Choose a name prefix for the library, more than two characters long. -All external function and variable names should start with this prefix. -In addition, there should only be one of these in any given library -member. This usually means putting each one in a separate source file. - - An exception can be made when two external symbols are always used -together, so that no reasonable program could use one without the -other; then they can both go in the same file. - - External symbols that are not documented entry points for the user -should have names beginning with `_'. They should also contain the -chosen name prefix for the library, to prevent collisions with other -libraries. These can go in the same files with user entry points if -you like. - - Static functions and variables can be used as you like and need not -fit any naming convention. - - -File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior - -Formatting Error Messages -========================= - - Error messages from compilers should look like this: - - SOURCE-FILE-NAME:LINENO: MESSAGE - - Error messages from other noninteractive programs should look like -this: - - PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE - -when there is an appropriate source file, or like this: - - PROGRAM: MESSAGE - -when there is no relevant source file. - - 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 -prompt or with the screen layout. (When the same program runs with -input from a source other than a terminal, it is not interactive and -would do best to print error messages using the noninteractive style.) - - The string MESSAGE should not begin with a capital letter when it -follows a program name and/or file name. Also, it should not end with -a period. - - Error messages from interactive programs, and other messages such as -usage messages, should start with a capital letter. But they should not -end with a period. - - -File: standards.info, Node: User Interfaces, Next: Memory Usage, Prev: Errors, Up: Program Behavior - -Standards for Command Line Interfaces -===================================== - - Please don't make the behavior of a utility depend on the name used -to invoke it. It is useful sometimes to make a link to a utility with -a different name, and that should not change what it does. - - Instead, use a run time option or a compilation switch or both to -select among the alternate behaviors. - - Likewise, please don't make the behavior of the program depend on the -type of output device it is used with. Device independence is an -important principle of the system's design; do not compromise it merely -to save someone from typing an option now and then. - - If you think one behavior is most useful when the output is to a -terminal, and another is most useful when the output is a file or a -pipe, then it is usually best to make the default behavior the one that -is useful with output to a terminal, and have an option for the other -behavior. - - Compatibility requires certain programs to depend on the type of -output device. It would be disastrous if `ls' or `sh' did not do so in -the way all users expect. In some of these cases, we supplement the -program with a preferred alternate version that does not depend on the -output device type. For example, we provide a `dir' program much like -`ls' except that its default output format is always multi-column -format. - - It is a good idea to follow the POSIX guidelines for the -command-line options of a program. The easiest way to do this is to use -`getopt' to parse them. Note that the GNU version of `getopt' will -normally permit options anywhere among the arguments unless the special -argument `--' is used. This is not what POSIX specifies; it is a GNU -extension. - - Please define long-named options that are equivalent to the -single-letter Unix-style options. We hope to make GNU more user -friendly this way. This is easy to do with the GNU function -`getopt_long'. - - One of the advantages of long-named options is that they can be -consistent from program to program. For example, users should be able -to expect the "verbose" option of any GNU program which has one, to be -spelled precisely `--verbose'. To achieve this uniformity, look at the -table of common long-option names when you choose the option names for -your program. The table appears below. - - If you use names not already in the table, please send -`gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can -update the table. - - It is usually a good idea for file names given as ordinary arguments -to be input files only; any output files would be specified using -options (preferably `-o'). Even if you allow an output file name as an -ordinary argument for compatibility, try to provide a suitable option -as well. This will lead to more consistency among GNU utilities, so -that there are fewer idiosyncracies for users to remember. - - Programs should support an option `--version' which prints the -program's version number on standard output and exits successfully, and -an option `--help' which prints option usage information on standard -output and exits successfully. These options should inhibit the normal -function of the command; they should do nothing except print the -requested information. - - Here is the table of long options used by GNU programs. - -`after-date' - `-N' in `tar'. - -`all' - `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'. - -`all-text' - `-a' in `diff'. - -`almost-all' - `-A' in `ls'. - -`append' - `-a' in `etags', `tee', `time'; `-r' in `tar'. - -`archive' - `-a' in `cp'. - -`archive-name' - `-n' in `shar'. - -`arglength' - `-l' in `m4'. - -`ascii' - `-a' in `diff'. - -`assign' - `-v' in `gawk'. - -`assume-new' - `-W' in Make. - -`assume-old' - `-o' in Make. - -`auto-check' - `-a' in `recode'. - -`auto-pager' - `-a' in `wdiff'. - -`auto-reference' - `-A' in `ptx'. - -`avoid-wraps' - `-n' in `wdiff'. - -`backward-search' - `-B' in `ctags'. - -`basename' - `-f' in `shar'. - -`batch' - Used in GDB. - -`baud' - Used in GDB. - -`before' - `-b' in `tac'. - -`binary' - `-b' in `cpio' and `diff'. - -`bits-per-code' - `-b' in `shar'. - -`block-size' - Used in `cpio' and `tar'. - -`blocks' - `-b' in `head' and `tail'. - -`break-file' - `-b' in `ptx'. - -`brief' - Used in various programs to make output shorter. - -`bytes' - `-c' in `head', `split', and `tail'. - -`c++' - `-C' in `etags'. - -`catenate' - `-A' in `tar'. - -`cd' - Used in various programs to specify the directory to use. - -`changes' - `-c' in `chgrp' and `chown'. - -`classify' - `-F' in `ls'. - -`colons' - `-c' in `recode'. - -`command' - `-c' in `su'; `-x' in GDB. - -`compare' - `-d' in `tar'. - -`compat' - Used in `gawk'. - -`compress' - `-Z' in `tar' and `shar'. - -`concatenate' - `-A' in `tar'. - -`confirmation' - `-w' in `tar'. - -`context' - Used in `diff'. - -`copyleft' - `-W copyleft' in `gawk'. - -`copyright' - `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'. - -`core' - Used in GDB. - -`count' - `-q' in `who'. - -`count-links' - `-l' in `du'. - -`create' - Used in `tar' and `cpio'. - -`cut-mark' - `-c' in `shar'. - -`cxref' - `-x' in `ctags'. - -`date' - `-d' in `touch'. - -`debug' - `-d' in Make and `m4'; `-t' in Bison. - -`define' - `-D' in `m4'. - -`defines' - `-d' in Bison and `ctags'. - -`delete' - `-D' in `tar'. - -`dereference' - `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'. - -`dereference-args' - `-D' in `du'. - -`diacritics' - `-d' in `recode'. - -`dictionary-order' - `-d' in `look'. - -`diff' - `-d' in `tar'. - -`digits' - `-n' in `csplit'. - -`directory' - Specify the directory to use, in various programs. In `ls', it - means to show directories themselves rather than their contents. - In `rm' and `ln', it means to not treat links to directories - specially. - -`discard-all' - `-x' in `strip'. - -`discard-locals' - `-X' in `strip'. - -`dry-run' - `-n' in Make. - -`ed' - `-e' in `diff'. - -`elide-empty-files' - `-z' in `csplit'. - -`end-delete' - `-x' in `wdiff'. - -`end-insert' - `-z' in `wdiff'. - -`entire-new-file' - `-N' in `diff'. - -`environment-overrides' - `-e' in Make. - -`eof' - `-e' in `xargs'. - -`epoch' - Used in GDB. - -`error-limit' - Used in `makeinfo'. - -`error-output' - `-o' in `m4'. - -`escape' - `-b' in `ls'. - -`exclude-from' - `-X' in `tar'. - -`exec' - Used in GDB. - -`exit' - `-x' in `xargs'. - -`exit-0' - `-e' in `unshar'. - -`expand-tabs' - `-t' in `diff'. - -`expression' - `-e' in `sed'. - -`extern-only' - `-g' in `nm'. - -`extract' - `-i' in `cpio'; `-x' in `tar'. - -`faces' - `-f' in `finger'. - -`fast' - `-f' in `su'. - -`fatal-warnings' - `-E' in `m4'. - -`file' - `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r' - in `touch'. - -`field-separator' - `-F' in `gawk'. - -`file-prefix' - `-b' in Bison. - -`file-type' - `-F' in `ls'. - -`files-from' - `-T' in `tar'. - -`fill-column' - Used in `makeinfo'. - -`flag-truncation' - `-F' in `ptx'. - -`fixed-output-files' - `-y' in Bison. - -`follow' - `-f' in `tail'. - -`footnote-style' - Used in `makeinfo'. - -`force' - `-f' in `cp', `ln', `mv', and `rm'. - -`force-prefix' - `-F' in `shar'. - -`format' - Used in `ls', `time', and `ptx'. - -`freeze-state' - `-F' in `m4'. - -`fullname' - Used in GDB. - -`gap-size' - `-g' in `ptx'. - -`get' - `-x' in `tar'. - -`graphic' - `-i' in `ul'. - -`graphics' - `-g' in `recode'. - -`group' - `-g' in `install'. - -`gzip' - `-z' in `tar' and `shar'. - -`hashsize' - `-H' in `m4'. - -`header' - `-h' in `objdump' and `recode' - -`heading' - `-H' in `who'. - -`help' - Used to ask for brief usage information. - -`here-delimiter' - `-d' in `shar'. - -`hide-control-chars' - `-q' in `ls'. - -`idle' - `-u' in `who'. - -`ifdef' - `-D' in `diff'. - -`ignore' - `-I' in `ls'; `-x' in `recode'. - -`ignore-all-space' - `-w' in `diff'. - -`ignore-backups' - `-B' in `ls'. - -`ignore-blank-lines' - `-B' in `diff'. - -`ignore-case' - `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'. - -`ignore-errors' - `-i' in Make. - -`ignore-file' - `-i' in `ptx'. - -`ignore-indentation' - `-I' in `etags'. - -`ignore-init-file' - `-f' in Oleo. - -`ignore-interrupts' - `-i' in `tee'. - -`ignore-matching-lines' - `-I' in `diff'. - -`ignore-space-change' - `-b' in `diff'. - -`ignore-zeros' - `-i' in `tar'. - -`include' - `-i' in `etags'; `-I' in `m4'. - -`include-dir' - `-I' in Make. - -`incremental' - `-G' in `tar'. - -`info' - `-i', `-l', and `-m' in Finger. - -`initial' - `-i' in `expand'. - -`initial-tab' - `-T' in `diff'. - -`inode' - `-i' in `ls'. - -`interactive' - `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs'; - `-w' in `tar'. - -`intermix-type' - `-p' in `shar'. - -`jobs' - `-j' in Make. - -`just-print' - `-n' in Make. - -`keep-going' - `-k' in Make. - -`keep-files' - `-k' in `csplit'. - -`kilobytes' - `-k' in `du' and `ls'. - -`language' - `-l' in `etags'. - -`less-mode' - `-l' in `wdiff'. - -`level-for-gzip' - `-g' in `shar'. - -`line-bytes' - `-C' in `split'. - -`lines' - Used in `split', `head', and `tail'. - -`link' - `-l' in `cpio'. - -`lint' -`lint-old' - Used in `gawk'. - -`list' - `-t' in `cpio'; `-l' in `recode'. - -`list' - `-t' in `tar'. - -`literal' - `-N' in `ls'. - -`load-average' - `-l' in Make. - -`login' - Used in `su'. - -`machine' - No listing of which programs already use this; someone should - check to see if any actually do and tell `gnu@prep.ai.mit.edu'. - -`macro-name' - `-M' in `ptx'. - -`mail' - `-m' in `hello' and `uname'. - -`make-directories' - `-d' in `cpio'. - -`makefile' - `-f' in Make. - -`mapped' - Used in GDB. - -`max-args' - `-n' in `xargs'. - -`max-chars' - `-n' in `xargs'. - -`max-lines' - `-l' in `xargs'. - -`max-load' - `-l' in Make. - -`max-procs' - `-P' in `xargs'. - -`mesg' - `-T' in `who'. - -`message' - `-T' in `who'. - -`minimal' - `-d' in `diff'. - -`mixed-uuencode' - `-M' in `shar'. - -`mode' - `-m' in `install', `mkdir', and `mkfifo'. - -`modification-time' - `-m' in `tar'. - -`multi-volume' - `-M' in `tar'. - -`name-prefix' - `-a' in Bison. - -`nesting-limit' - `-L' in `m4'. - -`net-headers' - `-a' in `shar'. - -`new-file' - `-W' in Make. - -`no-builtin-rules' - `-r' in Make. - -`no-character-count' - `-w' in `shar'. - -`no-check-existing' - `-x' in `shar'. - -`no-common' - `-3' in `wdiff'. - -`no-create' - `-c' in `touch'. - -`no-defines' - `-D' in `etags'. - -`no-deleted' - `-1' in `wdiff'. - -`no-dereference' - `-d' in `cp'. - -`no-inserted' - `-2' in `wdiff'. - -`no-keep-going' - `-S' in Make. - -`no-lines' - `-l' in Bison. - -`no-piping' - `-P' in `shar'. - -`no-prof' - `-e' in `gprof'. - -`no-regex' - `-R' in `etags'. - -`no-sort' - `-p' in `nm'. - -`no-split' - Used in `makeinfo'. - -`no-static' - `-a' in `gprof'. - -`no-time' - `-E' in `gprof'. - -`no-timestamp' - `-m' in `shar'. - -`no-validate' - Used in `makeinfo'. - -`no-warn' - Used in various programs to inhibit warnings. - -`node' - `-n' in `info'. - -`nodename' - `-n' in `uname'. - -`nonmatching' - `-f' in `cpio'. - -`nstuff' - `-n' in `objdump'. - -`null' - `-0' in `xargs'. - -`number' - `-n' in `cat'. - -`number-nonblank' - `-b' in `cat'. - -`numeric-sort' - `-n' in `nm'. - -`numeric-uid-gid' - `-n' in `cpio' and `ls'. - -`nx' - Used in GDB. - -`old-archive' - `-o' in `tar'. - -`old-file' - `-o' in Make. - -`one-file-system' - `-l' in `tar', `cp', and `du'. - -`only-file' - `-o' in `ptx'. - -`only-prof' - `-f' in `gprof'. - -`only-time' - `-F' in `gprof'. - -`output' - In various programs, specify the output file name. - -`output-prefix' - `-o' in `shar'. - -`override' - `-o' in `rm'. - -`overwrite' - `-c' in `unshar'. - -`owner' - `-o' in `install'. - -`paginate' - `-l' in `diff'. - -`paragraph-indent' - Used in `makeinfo'. - -`parents' - `-p' in `mkdir' and `rmdir'. - -`pass-all' - `-p' in `ul'. - -`pass-through' - `-p' in `cpio'. - -`port' - `-P' in `finger'. - -`portability' - `-c' in `cpio' and `tar'. - -`posix' - Used in `gawk'. - -`prefix-builtins' - `-P' in `m4'. - -`prefix' - `-f' in `csplit'. - -`preserve' - Used in `tar' and `cp'. - -`preserve-environment' - `-p' in `su'. - -`preserve-modification-time' - `-m' in `cpio'. - -`preserve-order' - `-s' in `tar'. - -`preserve-permissions' - `-p' in `tar'. - -`print' - `-l' in `diff'. - -`print-chars' - `-L' in `cmp'. - -`print-data-base' - `-p' in Make. - -`print-directory' - `-w' in Make. - -`print-file-name' - `-o' in `nm'. - -`print-symdefs' - `-s' in `nm'. - -`printer' - `-p' in `wdiff'. - -`prompt' - `-p' in `ed'. - -`query-user' - `-X' in `shar'. - -`question' - `-q' in Make. - -`quiet' - Used in many programs to inhibit the usual output. *Please note:* - every program accepting `--quiet' should accept `--silent' as a - synonym. - -`quiet-unshar' - `-Q' in `shar' - -`quote-name' - `-Q' in `ls'. - -`rcs' - `-n' in `diff'. - -`re-interval' - Used in `gawk'. - -`read-full-blocks' - `-B' in `tar'. - -`readnow' - Used in GDB. - -`recon' - `-n' in Make. - -`record-number' - `-R' in `tar'. - -`recursive' - Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'. - -`reference-limit' - Used in `makeinfo'. - -`references' - `-r' in `ptx'. - -`regex' - `-r' in `tac' and `etags'. - -`release' - `-r' in `uname'. - -`reload-state' - `-R' in `m4'. - -`relocation' - `-r' in `objdump'. - -`rename' - `-r' in `cpio'. - -`replace' - `-i' in `xargs'. - -`report-identical-files' - `-s' in `diff'. - -`reset-access-time' - `-a' in `cpio'. - -`reverse' - `-r' in `ls' and `nm'. - -`reversed-ed' - `-f' in `diff'. - -`right-side-defs' - `-R' in `ptx'. - -`same-order' - `-s' in `tar'. - -`same-permissions' - `-p' in `tar'. - -`save' - `-g' in `stty'. - -`se' - Used in GDB. - -`sentence-regexp' - `-S' in `ptx'. - -`separate-dirs' - `-S' in `du'. - -`separator' - `-s' in `tac'. - -`sequence' - Used by `recode' to chose files or pipes for sequencing passes. - -`shell' - `-s' in `su'. - -`show-all' - `-A' in `cat'. - -`show-c-function' - `-p' in `diff'. - -`show-ends' - `-E' in `cat'. - -`show-function-line' - `-F' in `diff'. - -`show-tabs' - `-T' in `cat'. - -`silent' - Used in many programs to inhibit the usual output. *Please note:* - every program accepting `--silent' should accept `--quiet' as a - synonym. - -`size' - `-s' in `ls'. - -`sort' - Used in `ls'. - -`source' - `-W source' in `gawk'. - -`sparse' - `-S' in `tar'. - -`speed-large-files' - `-H' in `diff'. - -`split-at' - `-E' in `unshar'. - -`split-size-limit' - `-L' in `shar'. - -`squeeze-blank' - `-s' in `cat'. - -`start-delete' - `-w' in `wdiff'. - -`start-insert' - `-y' in `wdiff'. - -`starting-file' - Used in `tar' and `diff' to specify which file within a directory - to start processing with. - -`statistics' - `-s' in `wdiff'. - -`stdin-file-list' - `-S' in `shar'. - -`stop' - `-S' in Make. - -`strict' - `-s' in `recode'. - -`strip' - `-s' in `install'. - -`strip-all' - `-s' in `strip'. - -`strip-debug' - `-S' in `strip'. - -`submitter' - `-s' in `shar'. - -`suffix' - `-S' in `cp', `ln', `mv'. - -`suffix-format' - `-b' in `csplit'. - -`sum' - `-s' in `gprof'. - -`summarize' - `-s' in `du'. - -`symbolic' - `-s' in `ln'. - -`symbols' - Used in GDB and `objdump'. - -`synclines' - `-s' in `m4'. - -`sysname' - `-s' in `uname'. - -`tabs' - `-t' in `expand' and `unexpand'. - -`tabsize' - `-T' in `ls'. - -`terminal' - `-T' in `tput' and `ul'. `-t' in `wdiff'. - -`text' - `-a' in `diff'. - -`text-files' - `-T' in `shar'. - -`time' - Used in `ls' and `touch'. - -`to-stdout' - `-O' in `tar'. - -`total' - `-c' in `du'. - -`touch' - `-t' in Make, `ranlib', and `recode'. - -`trace' - `-t' in `m4'. - -`traditional' - `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4', - and `ptx'. - -`tty' - Used in GDB. - -`typedefs' - `-t' in `ctags'. - -`typedefs-and-c++' - `-T' in `ctags'. - -`typeset-mode' - `-t' in `ptx'. - -`uncompress' - `-z' in `tar'. - -`unconditional' - `-u' in `cpio'. - -`undefine' - `-U' in `m4'. - -`undefined-only' - `-u' in `nm'. - -`update' - `-u' in `cp', `ctags', `mv', `tar'. - -`usage' - Used in `gawk'; same as `--help'. - -`uuencode' - `-B' in `shar'. - -`vanilla-operation' - `-V' in `shar'. - -`verbose' - Print more information about progress. Many programs support this. - -`verify' - `-W' in `tar'. - -`version' - Print the version number. - -`version-control' - `-V' in `cp', `ln', `mv'. - -`vgrind' - `-v' in `ctags'. - -`volume' - `-V' in `tar'. - -`what-if' - `-W' in Make. - -`whole-size-limit' - `-l' in `shar'. - -`width' - `-w' in `ls' and `ptx'. - -`word-regexp' - `-W' in `ptx'. - -`writable' - `-T' in `who'. - -`zeros' - `-z' in `gprof'. - - -File: standards.info, Node: Memory Usage, Prev: User Interfaces, Up: Program Behavior - -Memory Usage -============ - - If it 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 `cat' or `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 `malloc' returns zero. - - -File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top - -Making The Best Use of C -************************ - - This node 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 and Functions -* 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 - - -File: standards.info, Node: Formatting, Next: Comments, Up: Writing C - -Formatting Your Source Code -=========================== - - It is important to put the open-brace that starts the body of a C -function in column zero, and avoid putting any other open-brace or -open-parenthesis or open-bracket in column zero. Several tools look -for open-braces in column zero 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 zero. This helps people to search for function -definitions, and may also help certain tools recognize them. Thus, the -proper format is this: - - static char * - concat (s1, s2) /* Name starts in column zero here */ - char *s1, *s2; - { /* Open brace in column zero here */ - ... - } - -or, if you want to use ANSI C, format the definition like this: - - static char * - concat (char *s1, char *s2) - { - ... - } - - In ANSI C, if the arguments don't fit nicely on one line, split it -like this: - - int - lots_of_args (int an_integer, long a_long, short a_short, - double a_double, float a_float) - ... - - For the body of the function, we prefer code formatted like this: - - if (x < foo (y, z)) - haha = bar[4] + 5; - else - { - while (z) - { - haha += foo (z, z); - z--; - } - return ++x + bar (); - } - - 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: - - if (foo_this_is_long && bar > win (x, y, z) - && remaining_condition) - - Try to avoid having two operators of different precedence at the same -level of indentation. For example, don't write this: - - mode = (inmode[j] == VOIDmode - || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) - ? outmode[j] : inmode[j]); - - Instead, use extra parentheses so that the indentation shows the -nesting: - - mode = ((inmode[j] == VOIDmode - || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) - ? outmode[j] : inmode[j]); - - 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: - - 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; - - But adding a set of parentheses solves the problem: - - 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); - - Format do-while statements like this: - - do - { - a = foo (a); - } - while (a > 0); - - Please use formfeed characters (control-L) to divide the program into -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. - - -File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C - -Commenting Your Work -==================== - - Every program should start with a comment saying briefly what it is -for. Example: `fmt - filter for simple filling of text'. - - Please put a comment on each function saying what the function does, -what sorts of arguments it gets, and what the possible values of -arguments mean and are used for. It is not necessary to duplicate in -words the meaning of the C argument declarations, if a C type is being -used in its customary fashion. If there is anything nonstandard about -its use (such as an argument of type `char *' which is really the -address of the second character of a string, not the first), or any -possible values that would not work the way one would expect (such as, -that strings containing newlines are not guaranteed to work), be sure -to say so. - - Also explain the significance of the return value, if there is one. - - Please put two spaces after the end of a sentence in your comments, -so that the Emacs sentence commands will work. Also, please write -complete sentences and capitalize the first word. If a lower-case -identifier comes at the beginning of a sentence, don't capitalize it! -Changing the spelling makes it a different identifier. If you don't -like starting a sentence with a lower case letter, write the sentence -differently (e.g., "The identifier lower-case is ..."). - - The comment on a function is much clearer if you use the argument -names to speak about the argument values. The variable name itself -should be lower case, but write it in upper case when you are speaking -about the value rather than the variable itself. Thus, "the inode -number NODE_NUM" rather than "an inode". - - There is usually no purpose in restating the name of the function in -the comment before it, because the reader can see that for himself. -There might be an exception when the comment is so long that the -function itself would be off the bottom of the screen. - - There should be a comment on each static variable as well, like this: - - /* Nonzero means truncate lines in the display; - zero means continue them. */ - int truncate_lines; - - Every `#endif' should have a comment, except in the case of short -conditionals (just a few lines) that are not nested. The comment should -state the condition of the conditional that is ending, *including its -sense*. `#else' should have a comment describing the condition *and -sense* of the code that follows. For example: - - #ifdef foo - ... - #else /* not foo */ - ... - #endif /* not foo */ - -but, by contrast, write the comments this way for a `#ifndef': - - #ifndef foo - ... - #else /* foo */ - ... - #endif /* foo */ - - -File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C - -Clean Use of C Constructs -========================= - - Please explicitly declare all arguments to functions. Don't omit -them just because they are `int's. - - 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 should go in a header file. Don't put `extern' declarations inside -functions. - - It used to be common practice to use the same local variables (with -names like `tem') over and over for different values within one -function. Instead of doing this, it is better declare a separate local -variable for each distinct purpose, and give it a name which is -meaningful. This not only makes programs easier to understand, it also -facilitates optimization by good compilers. You can also move the -declaration of each local variable into the smallest scope that includes -all its uses. This makes the program even cleaner. - - Don't use local variables or parameters that shadow global -identifiers. - - Don't declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. For example, instead of -this: - - int foo, - bar; - -write either this: - - int foo, bar; - -or this: - - int foo; - int bar; - -(If they are global variables, each should have a comment preceding it -anyway.) - - When you have an `if'-`else' statement nested in another `if' -statement, always put braces around the `if'-`else'. Thus, never write -like this: - - if (foo) - if (bar) - win (); - else - lose (); - -always like this: - - if (foo) - { - if (bar) - win (); - else - lose (); - } - - If you have an `if' statement nested inside of an `else' statement, -either write `else if' on one line, like this, - - if (foo) - ... - else if (bar) - ... - -with its `then'-part indented like the preceding `then'-part, or write -the nested `if' within braces like this: - - if (foo) - ... - else - { - if (bar) - ... - } - - Don't declare both a structure tag and variables or typedefs in the -same declaration. Instead, declare the structure tag separately and -then use it to declare the variables or typedefs. - - Try to avoid assignments inside `if'-conditions. For example, don't -write this: - - if ((foo = (char *) malloc (sizeof *foo)) == 0) - fatal ("virtual memory exhausted"); - -instead, write this: - - foo = (char *) malloc (sizeof *foo); - if (foo == 0) - fatal ("virtual memory exhausted"); - - Don't make the program ugly to placate `lint'. Please don't insert -any casts to `void'. Zero without a cast is perfectly fine as a null -pointer constant, except when calling a varargs function. - - -File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C - -Naming Variables and Functions -============================== - - Please use underscores to separate words in a name, so that the Emacs -word commands can be useful within them. Stick to lower case; reserve -upper case for macros and `enum' constants, and for name-prefixes that -follow a uniform convention. - - For example, you should use names like `ignore_space_change_flag'; -don't use names like `iCantReadThis'. - - Variables that indicate whether command-line options have been -specified should be named after the meaning of the option, not after -the option-letter. A comment should state both the exact meaning of -the option and its letter. For example, - - /* Ignore changes in horizontal whitespace (-b). */ - int ignore_space_change_flag; - - When you want to define names with constant integer values, use -`enum' rather than `#define'. GDB knows about enumeration constants. - - Use file names of 14 characters or less, to avoid creating gratuitous -problems on older System V systems. You can use the program `doschk' -to test for this. `doschk' also tests for potential name conflicts if -the files were loaded onto an MS-DOS file system--something you may or -may not care about. - - -File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C - -Portability between System Types -================================ - - In the Unix world, "portability" refers to porting to different Unix -versions. For a GNU program, this kind of portability is desirable, but -not paramount. - - The primary purpose of GNU software is to run on top of the GNU -kernel, compiled with the GNU C compiler, on various types of CPU. The -amount and kinds of variation among GNU systems on different CPUs will -be comparable to the variation among Linux-based GNU systems or among -BSD systems today. So the kinds of portability that are absolutely -necessary are quite limited. - - But many users do run GNU software on non-GNU Unix or Unix-like -systems. So supporting a variety of Unix-like systems is desirable, -although not paramount. - - The easiest way to achieve portability to most Unix-like systems is -to use Autoconf. It's unlikely that your program needs to know more -information about the host platform than Autoconf can provide, simply -because most of the programs that need such knowledge have already been -written. - - Avoid using the format of semi-internal data bases (e.g., -directories) when there is a higher-level alternative (`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. -