1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename standards.info 4@settitle GNU Coding Standards 5@c This date is automagically updated when you save this file: 6@set lastupdate August 26, 1998 7@c %**end of header 8 9@ifinfo 10@format 11START-INFO-DIR-ENTRY 12* Standards: (standards). GNU coding standards. 13END-INFO-DIR-ENTRY 14@end format 15@end ifinfo 16 17@c @setchapternewpage odd 18@setchapternewpage off 19 20@c This is used by a cross ref in make-stds.texi 21@set CODESTD 1 22@iftex 23@set CHAPTER chapter 24@end iftex 25@ifinfo 26@set CHAPTER node 27@end ifinfo 28 29@ifinfo 30GNU Coding Standards 31Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc. 32 33Permission is granted to make and distribute verbatim copies of 34this manual provided the copyright notice and this permission notice 35are preserved on all copies. 36 37@ignore 38Permission is granted to process this file through TeX and print the 39results, provided the printed document carries copying permission 40notice identical to this one except for the removal of this paragraph 41(this paragraph not being relevant to the printed manual). 42@end ignore 43 44Permission is granted to copy and distribute modified versions of this 45manual under the conditions for verbatim copying, provided that the entire 46resulting derived work is distributed under the terms of a permission 47notice identical to this one. 48 49Permission is granted to copy and distribute translations of this manual 50into another language, under the above conditions for modified versions, 51except that this permission notice may be stated in a translation approved 52by the Free Software Foundation. 53@end ifinfo 54 55@titlepage 56@title GNU Coding Standards 57@author Richard Stallman 58@author last updated @value{lastupdate} 59@page 60 61@vskip 0pt plus 1filll 62Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc. 63 64Permission is granted to make and distribute verbatim copies of 65this manual provided the copyright notice and this permission notice 66are preserved on all copies. 67 68Permission is granted to copy and distribute modified versions of this 69manual under the conditions for verbatim copying, provided that the entire 70resulting derived work is distributed under the terms of a permission 71notice identical to this one. 72 73Permission is granted to copy and distribute translations of this manual 74into another language, under the above conditions for modified versions, 75except that this permission notice may be stated in a translation approved 76by the Free Software Foundation. 77@end titlepage 78 79@ifinfo 80@node Top, Preface, (dir), (dir) 81@top Version 82 83Last updated @value{lastupdate}. 84@end ifinfo 85 86@menu 87* Preface:: About the GNU Coding Standards 88* Intellectual Property:: Keeping Free Software Free 89* Design Advice:: General Program Design 90* Program Behavior:: Program Behavior for All Programs 91* Writing C:: Making The Best Use of C 92* Documentation:: Documenting Programs 93* Managing Releases:: The Release Process 94@end menu 95 96@node Preface 97@chapter About the GNU Coding Standards 98 99The GNU Coding Standards were written by Richard Stallman and other GNU 100Project volunteers. Their purpose is to make the GNU system clean, 101consistent, and easy to install. This document can also be read as a 102guide to writing portable, robust and reliable programs. It focuses on 103programs written in C, but many of the rules and principles are useful 104even if you write in another programming language. The rules often 105state reasons for writing in a certain way. 106 107Corrections or suggestions for this document should be sent to 108@email{gnu@@gnu.org}. If you make a suggestion, please include a 109suggested new wording for it; our time is limited. We prefer a context 110diff to the @file{standards.texi} or @file{make-stds.texi} files, but if 111you don't have those files, please mail your suggestion anyway. 112 113This release of the GNU Coding Standards was last updated 114@value{lastupdate}. 115 116@node Intellectual Property 117@chapter Keeping Free Software Free 118 119This @value{CHAPTER} discusses how you can make sure that GNU software 120remains unencumbered. 121 122@menu 123* Reading Non-Free Code:: Referring to Proprietary Programs 124* Contributions:: Accepting Contributions 125@end menu 126 127@node Reading Non-Free Code 128@section Referring to Proprietary Programs 129 130Don't in any circumstances refer to Unix source code for or during 131your work on GNU! (Or to any other proprietary programs.) 132 133If you have a vague recollection of the internals of a Unix program, 134this does not absolutely mean you can't write an imitation of it, but 135do try to organize the imitation internally along different lines, 136because this is likely to make the details of the Unix version 137irrelevant and dissimilar to your results. 138 139For example, Unix utilities were generally optimized to minimize 140memory use; if you go for speed instead, your program will be very 141different. You could keep the entire input file in core and scan it 142there instead of using stdio. Use a smarter algorithm discovered more 143recently than the Unix program. Eliminate use of temporary files. Do 144it in one pass instead of two (we did this in the assembler). 145 146Or, on the contrary, emphasize simplicity instead of speed. For some 147applications, the speed of today's computers makes simpler algorithms 148adequate. 149 150Or go for generality. For example, Unix programs often have static 151tables or fixed-size strings, which make for arbitrary limits; use 152dynamic allocation instead. Make sure your program handles NULs and 153other funny characters in the input files. Add a programming language 154for extensibility and write part of the program in that language. 155 156Or turn some parts of the program into independently usable libraries. 157Or use a simple garbage collector instead of tracking precisely when 158to free memory, or use a new GNU facility such as obstacks. 159 160 161@node Contributions 162@section Accepting Contributions 163 164If someone else sends you a piece of code to add to the program you are 165working on, we need legal papers to use it---the same sort of legal 166papers we will need to get from you. @emph{Each} significant 167contributor to a program must sign some sort of legal papers in order 168for us to have clear title to the program. The main author alone is not 169enough. 170 171So, before adding in any contributions from other people, please tell 172us, so we can arrange to get the papers. Then wait until we tell you 173that we have received the signed papers, before you actually use the 174contribution. 175 176This applies both before you release the program and afterward. If 177you receive diffs to fix a bug, and they make significant changes, we 178need legal papers for that change. 179 180This also applies to comments and documentation files. For copyright 181law, comments and code are just text. Copyright applies to all kinds of 182text, so we need legal papers for all kinds. 183 184You don't need papers for changes of a few lines here or there, since 185they are not significant for copyright purposes. Also, you don't need 186papers if all you get from the suggestion is some ideas, not actual code 187which you use. For example, if you write a different solution to the 188problem, you don't need to get papers. 189 190We know this is frustrating; it's frustrating for us as well. But if 191you don't wait, you are going out on a limb---for example, what if the 192contributor's employer won't sign a disclaimer? You might have to take 193that code out again! 194 195The very worst thing is if you forget to tell us about the other 196contributor. We could be very embarrassed in court some day as a 197result. 198 199We have more detailed advice for maintainers of programs; if you have 200reached the stage of actually maintaining a program for GNU (whether 201released or not), please ask us for a copy. 202 203@node Design Advice 204@chapter General Program Design 205 206This @value{CHAPTER} discusses some of the issues you should take into 207account when designing your program. 208 209@menu 210* Compatibility:: Compatibility with other implementations 211* Using Extensions:: Using non-standard features 212* ANSI C:: Using ANSI C features 213* Source Language:: Using languages other than C 214@end menu 215 216@node Compatibility 217@section Compatibility with Other Implementations 218 219With occasional exceptions, utility programs and libraries for GNU 220should be upward compatible with those in Berkeley Unix, and upward 221compatible with @sc{ansi} C if @sc{ansi} C specifies their behavior, and 222upward compatible with @sc{posix} if @sc{posix} specifies their 223behavior. 224 225When these standards conflict, it is useful to offer compatibility 226modes for each of them. 227 228@sc{ansi} C and @sc{posix} prohibit many kinds of extensions. Feel free 229to make the extensions anyway, and include a @samp{--ansi}, 230@samp{--posix}, or @samp{--compatible} option to turn them off. 231However, if the extension has a significant chance of breaking any real 232programs or scripts, then it is not really upward compatible. Try to 233redesign its interface. 234 235Many GNU programs suppress extensions that conflict with @sc{posix} if the 236environment variable @code{POSIXLY_CORRECT} is defined (even if it is 237defined with a null value). Please make your program recognize this 238variable if appropriate. 239 240When a feature is used only by users (not by programs or command 241files), and it is done poorly in Unix, feel free to replace it 242completely with something totally different and better. (For example, 243@code{vi} is replaced with Emacs.) But it is nice to offer a compatible 244feature as well. (There is a free @code{vi} clone, so we offer it.) 245 246Additional useful features not in Berkeley Unix are welcome. 247 248@node Using Extensions 249@section Using Non-standard Features 250 251Many GNU facilities that already exist support a number of convenient 252extensions over the comparable Unix facilities. Whether to use these 253extensions in implementing your program is a difficult question. 254 255On the one hand, using the extensions can make a cleaner program. 256On the other hand, people will not be able to build the program 257unless the other GNU tools are available. This might cause the 258program to work on fewer kinds of machines. 259 260With some extensions, it might be easy to provide both alternatives. 261For example, you can define functions with a ``keyword'' @code{INLINE} 262and define that as a macro to expand into either @code{inline} or 263nothing, depending on the compiler. 264 265In general, perhaps it is best not to use the extensions if you can 266straightforwardly do without them, but to use the extensions if they 267are a big improvement. 268 269An exception to this rule are the large, established programs (such as 270Emacs) which run on a great variety of systems. Such programs would 271be broken by use of GNU extensions. 272 273Another exception is for programs that are used as part of 274compilation: anything that must be compiled with other compilers in 275order to bootstrap the GNU compilation facilities. If these require 276the GNU compiler, then no one can compile them without having them 277installed already. That would be no good. 278 279@node ANSI C 280@section @sc{ansi} C and pre-@sc{ansi} C 281 282Do not ever use the ``trigraph'' feature of @sc{ansi} C. 283 284@sc{ansi} C is widespread enough now that it is ok to write new programs 285that use @sc{ansi} C features (and therefore will not work in 286non-@sc{ansi} compilers). And if a program is already written in 287@sc{ansi} C, there's no need to convert it to support non-@sc{ansi} 288compilers. 289 290However, it is easy to support non-@sc{ansi} compilers in most programs, 291so you might still consider doing so when you write a program. Instead 292of writing function definitions in @sc{ansi} prototype form, 293 294@example 295int 296foo (int x, int y) 297@dots{} 298@end example 299 300@noindent 301write the definition in pre-@sc{ansi} style like this, 302 303@example 304int 305foo (x, y) 306 int x, y; 307@dots{} 308@end example 309 310@noindent 311and use a separate declaration to specify the argument prototype: 312 313@example 314int foo (int, int); 315@end example 316 317You need such a declaration anyway, in a header file, to get the benefit 318of @sc{ansi} C prototypes in all the files where the function is called. 319And once you have it, you lose nothing by writing the function 320definition in the pre-@sc{ansi} style. 321 322If you don't know non-@sc{ansi} C, there's no need to learn it; just 323write in @sc{ansi} C. 324 325@node Source Language 326@section Using Languages Other Than C 327 328Using a language other than C is like using a non-standard feature: it 329will cause trouble for users. Even if GCC supports the other language, 330users may find it inconvenient to have to install the compiler for that 331other language in order to build your program. For example, if you 332write your program in C++, people will have to install the C++ compiler 333in order to compile your program. Thus, it is better if you write in C. 334 335But there are three situations when there is no disadvantage in using 336some other language: 337 338@itemize @bullet 339@item 340It is okay to use another language if your program contains an 341interpreter for that language. 342 343For example, if your program links with GUILE, it is ok to write part of 344the program in Scheme or another language supported by GUILE. 345 346@item 347It is okay to use another language in a tool specifically intended for 348use with that language. 349 350This is okay because the only people who want to build the tool will be 351those who have installed the other language anyway. 352 353@item 354If an application is of interest to a narrow community, then perhaps 355it's not important if the application is inconvenient to install. 356@end itemize 357 358C has one other advantage over C++ and other compiled languages: more 359people know C, so more people will find it easy to read and modify the 360program if it is written in C. 361 362@node Program Behavior 363@chapter Program Behavior for All Programs 364 365This @value{CHAPTER} describes how to write robust software. It also 366describes general standards for error messages, the command line interface, 367and how libraries should behave. 368 369@menu 370* Semantics:: Writing robust programs 371* Libraries:: Library behavior 372* Errors:: Formatting error messages 373* User Interfaces:: Standards for command line interfaces 374* Option Table:: Table of long options. 375* Memory Usage:: When and how to care about memory needs 376@end menu 377 378@node Semantics 379@section Writing Robust Programs 380 381Avoid arbitrary limits on the length or number of @emph{any} data 382structure, including file names, lines, files, and symbols, by allocating 383all data structures dynamically. In most Unix utilities, ``long lines 384are silently truncated''. This is not acceptable in a GNU utility. 385 386Utilities reading files should not drop NUL characters, or any other 387nonprinting characters @emph{including those with codes above 0177}. The 388only sensible exceptions would be utilities specifically intended for 389interface to certain types of printers that can't handle those characters. 390 391Check every system call for an error return, unless you know you wish to 392ignore errors. Include the system error text (from @code{perror} or 393equivalent) in @emph{every} error message resulting from a failing 394system call, as well as the name of the file if any and the name of the 395utility. Just ``cannot open foo.c'' or ``stat failed'' is not 396sufficient. 397 398Check every call to @code{malloc} or @code{realloc} to see if it 399returned zero. Check @code{realloc} even if you are making the block 400smaller; in a system that rounds block sizes to a power of 2, 401@code{realloc} may get a different block if you ask for less space. 402 403In Unix, @code{realloc} can destroy the storage block if it returns 404zero. GNU @code{realloc} does not have this bug: if it fails, the 405original block is unchanged. Feel free to assume the bug is fixed. If 406you wish to run your program on Unix, and wish to avoid lossage in this 407case, you can use the GNU @code{malloc}. 408 409You must expect @code{free} to alter the contents of the block that was 410freed. Anything you want to fetch from the block, you must fetch before 411calling @code{free}. 412 413If @code{malloc} fails in a noninteractive program, make that a fatal 414error. In an interactive program (one that reads commands from the 415user), it is better to abort the command and return to the command 416reader loop. This allows the user to kill other processes to free up 417virtual memory, and then try the command again. 418 419Use @code{getopt_long} to decode arguments, unless the argument syntax 420makes this unreasonable. 421 422When static storage is to be written in during program execution, use 423explicit C code to initialize it. Reserve C initialized declarations 424for data that will not be changed. 425@c ADR: why? 426 427Try to avoid low-level interfaces to obscure Unix data structures (such 428as file directories, utmp, or the layout of kernel memory), since these 429are less likely to work compatibly. If you need to find all the files 430in a directory, use @code{readdir} or some other high-level interface. 431These will be supported compatibly by GNU. 432 433The preferred signal handling facilities are the BSD variant of 434@code{signal}, and the @sc{posix} @code{sigaction} function; the 435alternative USG @code{signal} interface is an inferior design. 436 437Nowadays, using the @sc{posix} signal functions may be the easiest way 438to make a program portable. If you use @code{signal}, then on GNU/Linux 439systems running GNU libc version 1, you should include 440@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD 441behavior. It is up to you whether to support systems where 442@code{signal} has only the USG behavior, or give up on them. 443 444In error checks that detect ``impossible'' conditions, just abort. 445There is usually no point in printing any message. These checks 446indicate the existence of bugs. Whoever wants to fix the bugs will have 447to read the source code and run a debugger. So explain the problem with 448comments in the source. The relevant data will be in variables, which 449are easy to examine with the debugger, so there is no point moving them 450elsewhere. 451 452Do not use a count of errors as the exit status for a program. 453@emph{That does not work}, because exit status values are limited to 8 454bits (0 through 255). A single run of the program might have 256 455errors; if you try to return 256 as the exit status, the parent process 456will see 0 as the status, and it will appear that the program succeeded. 457 458If you make temporary files, check the @code{TMPDIR} environment 459variable; if that variable is defined, use the specified directory 460instead of @file{/tmp}. 461 462@node Libraries 463@section Library Behavior 464 465Try to make library functions reentrant. If they need to do dynamic 466storage allocation, at least try to avoid any nonreentrancy aside from 467that of @code{malloc} itself. 468 469Here are certain name conventions for libraries, to avoid name 470conflicts. 471 472Choose a name prefix for the library, more than two characters long. 473All external function and variable names should start with this 474prefix. In addition, there should only be one of these in any given 475library member. This usually means putting each one in a separate 476source file. 477 478An exception can be made when two external symbols are always used 479together, so that no reasonable program could use one without the 480other; then they can both go in the same file. 481 482External symbols that are not documented entry points for the user 483should have names beginning with @samp{_}. They should also contain 484the chosen name prefix for the library, to prevent collisions with 485other libraries. These can go in the same files with user entry 486points if you like. 487 488Static functions and variables can be used as you like and need not 489fit any naming convention. 490 491@node Errors 492@section Formatting Error Messages 493 494Error messages from compilers should look like this: 495 496@example 497@var{source-file-name}:@var{lineno}: @var{message} 498@end example 499 500Error messages from other noninteractive programs should look like this: 501 502@example 503@var{program}:@var{source-file-name}:@var{lineno}: @var{message} 504@end example 505 506@noindent 507when there is an appropriate source file, or like this: 508 509@example 510@var{program}: @var{message} 511@end example 512 513@noindent 514when there is no relevant source file. 515 516In an interactive program (one that is reading commands from a 517terminal), it is better not to include the program name in an error 518message. The place to indicate which program is running is in the 519prompt or with the screen layout. (When the same program runs with 520input from a source other than a terminal, it is not interactive and 521would do best to print error messages using the noninteractive style.) 522 523The string @var{message} should not begin with a capital letter when 524it follows a program name and/or file name. Also, it should not end 525with a period. 526 527Error messages from interactive programs, and other messages such as 528usage messages, should start with a capital letter. But they should not 529end with a period. 530 531@node User Interfaces 532@section Standards for Command Line Interfaces 533 534Please don't make the behavior of a utility depend on the name used 535to invoke it. It is useful sometimes to make a link to a utility 536with a different name, and that should not change what it does. 537 538Instead, use a run time option or a compilation switch or both 539to select among the alternate behaviors. 540 541Likewise, please don't make the behavior of the program depend on the 542type of output device it is used with. Device independence is an 543important principle of the system's design; do not compromise it merely 544to save someone from typing an option now and then. (Variation in error 545message syntax when using a terminal is ok, because that is a side issue 546that people do not depend on.) 547 548If you think one behavior is most useful when the output is to a 549terminal, and another is most useful when the output is a file or a 550pipe, then it is usually best to make the default behavior the one that 551is useful with output to a terminal, and have an option for the other 552behavior. 553 554Compatibility requires certain programs to depend on the type of output 555device. It would be disastrous if @code{ls} or @code{sh} did not do so 556in the way all users expect. In some of these cases, we supplement the 557program with a preferred alternate version that does not depend on the 558output device type. For example, we provide a @code{dir} program much 559like @code{ls} except that its default output format is always 560multi-column format. 561 562It is a good idea to follow the @sc{posix} guidelines for the 563command-line options of a program. The easiest way to do this is to use 564@code{getopt} to parse them. Note that the GNU version of @code{getopt} 565will normally permit options anywhere among the arguments unless the 566special argument @samp{--} is used. This is not what @sc{posix} 567specifies; it is a GNU extension. 568 569Please define long-named options that are equivalent to the 570single-letter Unix-style options. We hope to make GNU more user 571friendly this way. This is easy to do with the GNU function 572@code{getopt_long}. 573 574One of the advantages of long-named options is that they can be 575consistent from program to program. For example, users should be able 576to expect the ``verbose'' option of any GNU program which has one, to be 577spelled precisely @samp{--verbose}. To achieve this uniformity, look at 578the table of common long-option names when you choose the option names 579for your program (@pxref{Option Table}). 580 581It is usually a good idea for file names given as ordinary arguments to 582be input files only; any output files would be specified using options 583(preferably @samp{-o} or @samp{--output}). Even if you allow an output 584file name as an ordinary argument for compatibility, try to provide an 585option as another way to specify it. This will lead to more consistency 586among GNU utilities, and fewer idiosyncracies for users to remember. 587 588All programs should support two standard options: @samp{--version} 589and @samp{--help}. 590 591@table @code 592@item --version 593This option should direct the program to information about its name, 594version, origin and legal status, all on standard output, and then exit 595successfully. Other options and arguments should be ignored once this 596is seen, and the program should not perform its normal function. 597 598The first line is meant to be easy for a program to parse; the version 599number proper starts after the last space. In addition, it contains 600the canonical name for this program, in this format: 601 602@example 603GNU Emacs 19.30 604@end example 605 606@noindent 607The program's name should be a constant string; @emph{don't} compute it 608from @code{argv[0]}. The idea is to state the standard or canonical 609name for the program, not its file name. There are other ways to find 610out the precise file name where a command is found in @code{PATH}. 611 612If the program is a subsidiary part of a larger package, mention the 613package name in parentheses, like this: 614 615@example 616emacsserver (GNU Emacs) 19.30 617@end example 618 619@noindent 620If the package has a version number which is different from this 621program's version number, you can mention the package version number 622just before the close-parenthesis. 623 624If you @strong{need} to mention the version numbers of libraries which 625are distributed separately from the package which contains this program, 626you can do so by printing an additional line of version info for each 627library you want to mention. Use the same format for these lines as for 628the first line. 629 630Please do not mention all of the libraries that the program uses ``just 631for completeness''---that would produce a lot of unhelpful clutter. 632Please mention library version numbers only if you find in practice that 633they are very important to you in debugging. 634 635The following line, after the version number line or lines, should be a 636copyright notice. If more than one copyright notice is called for, put 637each on a separate line. 638 639Next should follow a brief statement that the program is free software, 640and that users are free to copy and change it on certain conditions. If 641the program is covered by the GNU GPL, say so here. Also mention that 642there is no warranty, to the extent permitted by law. 643 644It is ok to finish the output with a list of the major authors of the 645program, as a way of giving credit. 646 647Here's an example of output that follows these rules: 648 649@smallexample 650GNU Emacs 19.34.5 651Copyright (C) 1996 Free Software Foundation, Inc. 652GNU Emacs comes with NO WARRANTY, 653to the extent permitted by law. 654You may redistribute copies of GNU Emacs 655under the terms of the GNU General Public License. 656For more information about these matters, 657see the files named COPYING. 658@end smallexample 659 660You should adapt this to your program, of course, filling in the proper 661year, copyright holder, name of program, and the references to 662distribution terms, and changing the rest of the wording as necessary. 663 664This copyright notice only needs to mention the most recent year in 665which changes were made---there's no need to list the years for previous 666versions' changes. You don't have to mention the name of the program in 667these notices, if that is inconvenient, since it appeared in the first 668line. 669 670@item --help 671This option should output brief documentation for how to invoke the 672program, on standard output, then exit successfully. Other options and 673arguments should be ignored once this is seen, and the program should 674not perform its normal function. 675 676Near the end of the @samp{--help} option's output there should be a line 677that says where to mail bug reports. It should have this format: 678 679@example 680Report bugs to @var{mailing-address}. 681@end example 682@end table 683 684@node Option Table 685@section Table of Long Options 686 687Here is a table of long options used by GNU programs. It is surely 688incomplete, but we aim to list all the options that a new program might 689want to be compatible with. If you use names not already in the table, 690please send @email{gnu@@gnu.org} a list of them, with their 691meanings, so we can update the table. 692 693@c Please leave newlines between items in this table; it's much easier 694@c to update when it isn't completely squashed together and unreadable. 695@c When there is more than one short option for a long option name, put 696@c a semicolon between the lists of the programs that use them, not a 697@c period. --friedman 698 699@table @samp 700@item after-date 701@samp{-N} in @code{tar}. 702 703@item all 704@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, 705and @code{unexpand}. 706 707@item all-text 708@samp{-a} in @code{diff}. 709 710@item almost-all 711@samp{-A} in @code{ls}. 712 713@item append 714@samp{-a} in @code{etags}, @code{tee}, @code{time}; 715@samp{-r} in @code{tar}. 716 717@item archive 718@samp{-a} in @code{cp}. 719 720@item archive-name 721@samp{-n} in @code{shar}. 722 723@item arglength 724@samp{-l} in @code{m4}. 725 726@item ascii 727@samp{-a} in @code{diff}. 728 729@item assign 730@samp{-v} in @code{gawk}. 731 732@item assume-new 733@samp{-W} in Make. 734 735@item assume-old 736@samp{-o} in Make. 737 738@item auto-check 739@samp{-a} in @code{recode}. 740 741@item auto-pager 742@samp{-a} in @code{wdiff}. 743 744@item auto-reference 745@samp{-A} in @code{ptx}. 746 747@item avoid-wraps 748@samp{-n} in @code{wdiff}. 749 750@item background 751For server programs, run in the background. 752 753@item backward-search 754@samp{-B} in @code{ctags}. 755 756@item basename 757@samp{-f} in @code{shar}. 758 759@item batch 760Used in GDB. 761 762@item baud 763Used in GDB. 764 765@item before 766@samp{-b} in @code{tac}. 767 768@item binary 769@samp{-b} in @code{cpio} and @code{diff}. 770 771@item bits-per-code 772@samp{-b} in @code{shar}. 773 774@item block-size 775Used in @code{cpio} and @code{tar}. 776 777@item blocks 778@samp{-b} in @code{head} and @code{tail}. 779 780@item break-file 781@samp{-b} in @code{ptx}. 782 783@item brief 784Used in various programs to make output shorter. 785 786@item bytes 787@samp{-c} in @code{head}, @code{split}, and @code{tail}. 788 789@item c@t{++} 790@samp{-C} in @code{etags}. 791 792@item catenate 793@samp{-A} in @code{tar}. 794 795@item cd 796Used in various programs to specify the directory to use. 797 798@item changes 799@samp{-c} in @code{chgrp} and @code{chown}. 800 801@item classify 802@samp{-F} in @code{ls}. 803 804@item colons 805@samp{-c} in @code{recode}. 806 807@item command 808@samp{-c} in @code{su}; 809@samp{-x} in GDB. 810 811@item compare 812@samp{-d} in @code{tar}. 813 814@item compat 815Used in @code{gawk}. 816 817@item compress 818@samp{-Z} in @code{tar} and @code{shar}. 819 820@item concatenate 821@samp{-A} in @code{tar}. 822 823@item confirmation 824@samp{-w} in @code{tar}. 825 826@item context 827Used in @code{diff}. 828 829@item copyleft 830@samp{-W copyleft} in @code{gawk}. 831 832@item copyright 833@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; 834@samp{-W copyright} in @code{gawk}. 835 836@item core 837Used in GDB. 838 839@item count 840@samp{-q} in @code{who}. 841 842@item count-links 843@samp{-l} in @code{du}. 844 845@item create 846Used in @code{tar} and @code{cpio}. 847 848@item cut-mark 849@samp{-c} in @code{shar}. 850 851@item cxref 852@samp{-x} in @code{ctags}. 853 854@item date 855@samp{-d} in @code{touch}. 856 857@item debug 858@samp{-d} in Make and @code{m4}; 859@samp{-t} in Bison. 860 861@item define 862@samp{-D} in @code{m4}. 863 864@item defines 865@samp{-d} in Bison and @code{ctags}. 866 867@item delete 868@samp{-D} in @code{tar}. 869 870@item dereference 871@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, 872@code{ls}, and @code{tar}. 873 874@item dereference-args 875@samp{-D} in @code{du}. 876 877@item diacritics 878@samp{-d} in @code{recode}. 879 880@item dictionary-order 881@samp{-d} in @code{look}. 882 883@item diff 884@samp{-d} in @code{tar}. 885 886@item digits 887@samp{-n} in @code{csplit}. 888 889@item directory 890Specify the directory to use, in various programs. In @code{ls}, it 891means to show directories themselves rather than their contents. In 892@code{rm} and @code{ln}, it means to not treat links to directories 893specially. 894 895@item discard-all 896@samp{-x} in @code{strip}. 897 898@item discard-locals 899@samp{-X} in @code{strip}. 900 901@item dry-run 902@samp{-n} in Make. 903 904@item ed 905@samp{-e} in @code{diff}. 906 907@item elide-empty-files 908@samp{-z} in @code{csplit}. 909 910@item end-delete 911@samp{-x} in @code{wdiff}. 912 913@item end-insert 914@samp{-z} in @code{wdiff}. 915 916@item entire-new-file 917@samp{-N} in @code{diff}. 918 919@item environment-overrides 920@samp{-e} in Make. 921 922@item eof 923@samp{-e} in @code{xargs}. 924 925@item epoch 926Used in GDB. 927 928@item error-limit 929Used in @code{makeinfo}. 930 931@item error-output 932@samp{-o} in @code{m4}. 933 934@item escape 935@samp{-b} in @code{ls}. 936 937@item exclude-from 938@samp{-X} in @code{tar}. 939 940@item exec 941Used in GDB. 942 943@item exit 944@samp{-x} in @code{xargs}. 945 946@item exit-0 947@samp{-e} in @code{unshar}. 948 949@item expand-tabs 950@samp{-t} in @code{diff}. 951 952@item expression 953@samp{-e} in @code{sed}. 954 955@item extern-only 956@samp{-g} in @code{nm}. 957 958@item extract 959@samp{-i} in @code{cpio}; 960@samp{-x} in @code{tar}. 961 962@item faces 963@samp{-f} in @code{finger}. 964 965@item fast 966@samp{-f} in @code{su}. 967 968@item fatal-warnings 969@samp{-E} in @code{m4}. 970 971@item file 972@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar}; 973@samp{-n} in @code{sed}; 974@samp{-r} in @code{touch}. 975 976@item field-separator 977@samp{-F} in @code{gawk}. 978 979@item file-prefix 980@samp{-b} in Bison. 981 982@item file-type 983@samp{-F} in @code{ls}. 984 985@item files-from 986@samp{-T} in @code{tar}. 987 988@item fill-column 989Used in @code{makeinfo}. 990 991@item flag-truncation 992@samp{-F} in @code{ptx}. 993 994@item fixed-output-files 995@samp{-y} in Bison. 996 997@item follow 998@samp{-f} in @code{tail}. 999 1000@item footnote-style 1001Used in @code{makeinfo}. 1002 1003@item force 1004@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. 1005 1006@item force-prefix 1007@samp{-F} in @code{shar}. 1008 1009@item foreground 1010For server programs, run in the foreground; 1011in other words, don't do anything special to run the server 1012in the background. 1013 1014@item format 1015Used in @code{ls}, @code{time}, and @code{ptx}. 1016 1017@item freeze-state 1018@samp{-F} in @code{m4}. 1019 1020@item fullname 1021Used in GDB. 1022 1023@item gap-size 1024@samp{-g} in @code{ptx}. 1025 1026@item get 1027@samp{-x} in @code{tar}. 1028 1029@item graphic 1030@samp{-i} in @code{ul}. 1031 1032@item graphics 1033@samp{-g} in @code{recode}. 1034 1035@item group 1036@samp{-g} in @code{install}. 1037 1038@item gzip 1039@samp{-z} in @code{tar} and @code{shar}. 1040 1041@item hashsize 1042@samp{-H} in @code{m4}. 1043 1044@item header 1045@samp{-h} in @code{objdump} and @code{recode} 1046 1047@item heading 1048@samp{-H} in @code{who}. 1049 1050@item help 1051Used to ask for brief usage information. 1052 1053@item here-delimiter 1054@samp{-d} in @code{shar}. 1055 1056@item hide-control-chars 1057@samp{-q} in @code{ls}. 1058 1059@item idle 1060@samp{-u} in @code{who}. 1061 1062@item ifdef 1063@samp{-D} in @code{diff}. 1064 1065@item ignore 1066@samp{-I} in @code{ls}; 1067@samp{-x} in @code{recode}. 1068 1069@item ignore-all-space 1070@samp{-w} in @code{diff}. 1071 1072@item ignore-backups 1073@samp{-B} in @code{ls}. 1074 1075@item ignore-blank-lines 1076@samp{-B} in @code{diff}. 1077 1078@item ignore-case 1079@samp{-f} in @code{look} and @code{ptx}; 1080@samp{-i} in @code{diff} and @code{wdiff}. 1081 1082@item ignore-errors 1083@samp{-i} in Make. 1084 1085@item ignore-file 1086@samp{-i} in @code{ptx}. 1087 1088@item ignore-indentation 1089@samp{-I} in @code{etags}. 1090 1091@item ignore-init-file 1092@samp{-f} in Oleo. 1093 1094@item ignore-interrupts 1095@samp{-i} in @code{tee}. 1096 1097@item ignore-matching-lines 1098@samp{-I} in @code{diff}. 1099 1100@item ignore-space-change 1101@samp{-b} in @code{diff}. 1102 1103@item ignore-zeros 1104@samp{-i} in @code{tar}. 1105 1106@item include 1107@samp{-i} in @code{etags}; 1108@samp{-I} in @code{m4}. 1109 1110@item include-dir 1111@samp{-I} in Make. 1112 1113@item incremental 1114@samp{-G} in @code{tar}. 1115 1116@item info 1117@samp{-i}, @samp{-l}, and @samp{-m} in Finger. 1118 1119@item initial 1120@samp{-i} in @code{expand}. 1121 1122@item initial-tab 1123@samp{-T} in @code{diff}. 1124 1125@item inode 1126@samp{-i} in @code{ls}. 1127 1128@item interactive 1129@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; 1130@samp{-e} in @code{m4}; 1131@samp{-p} in @code{xargs}; 1132@samp{-w} in @code{tar}. 1133 1134@item intermix-type 1135@samp{-p} in @code{shar}. 1136 1137@item jobs 1138@samp{-j} in Make. 1139 1140@item just-print 1141@samp{-n} in Make. 1142 1143@item keep-going 1144@samp{-k} in Make. 1145 1146@item keep-files 1147@samp{-k} in @code{csplit}. 1148 1149@item kilobytes 1150@samp{-k} in @code{du} and @code{ls}. 1151 1152@item language 1153@samp{-l} in @code{etags}. 1154 1155@item less-mode 1156@samp{-l} in @code{wdiff}. 1157 1158@item level-for-gzip 1159@samp{-g} in @code{shar}. 1160 1161@item line-bytes 1162@samp{-C} in @code{split}. 1163 1164@item lines 1165Used in @code{split}, @code{head}, and @code{tail}. 1166 1167@item link 1168@samp{-l} in @code{cpio}. 1169 1170@item lint 1171@itemx lint-old 1172Used in @code{gawk}. 1173 1174@item list 1175@samp{-t} in @code{cpio}; 1176@samp{-l} in @code{recode}. 1177 1178@item list 1179@samp{-t} in @code{tar}. 1180 1181@item literal 1182@samp{-N} in @code{ls}. 1183 1184@item load-average 1185@samp{-l} in Make. 1186 1187@item login 1188Used in @code{su}. 1189 1190@item machine 1191No listing of which programs already use this; 1192someone should check to 1193see if any actually do, and tell @email{gnu@@gnu.org}. 1194 1195@item macro-name 1196@samp{-M} in @code{ptx}. 1197 1198@item mail 1199@samp{-m} in @code{hello} and @code{uname}. 1200 1201@item make-directories 1202@samp{-d} in @code{cpio}. 1203 1204@item makefile 1205@samp{-f} in Make. 1206 1207@item mapped 1208Used in GDB. 1209 1210@item max-args 1211@samp{-n} in @code{xargs}. 1212 1213@item max-chars 1214@samp{-n} in @code{xargs}. 1215 1216@item max-lines 1217@samp{-l} in @code{xargs}. 1218 1219@item max-load 1220@samp{-l} in Make. 1221 1222@item max-procs 1223@samp{-P} in @code{xargs}. 1224 1225@item mesg 1226@samp{-T} in @code{who}. 1227 1228@item message 1229@samp{-T} in @code{who}. 1230 1231@item minimal 1232@samp{-d} in @code{diff}. 1233 1234@item mixed-uuencode 1235@samp{-M} in @code{shar}. 1236 1237@item mode 1238@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. 1239 1240@item modification-time 1241@samp{-m} in @code{tar}. 1242 1243@item multi-volume 1244@samp{-M} in @code{tar}. 1245 1246@item name-prefix 1247@samp{-a} in Bison. 1248 1249@item nesting-limit 1250@samp{-L} in @code{m4}. 1251 1252@item net-headers 1253@samp{-a} in @code{shar}. 1254 1255@item new-file 1256@samp{-W} in Make. 1257 1258@item no-builtin-rules 1259@samp{-r} in Make. 1260 1261@item no-character-count 1262@samp{-w} in @code{shar}. 1263 1264@item no-check-existing 1265@samp{-x} in @code{shar}. 1266 1267@item no-common 1268@samp{-3} in @code{wdiff}. 1269 1270@item no-create 1271@samp{-c} in @code{touch}. 1272 1273@item no-defines 1274@samp{-D} in @code{etags}. 1275 1276@item no-deleted 1277@samp{-1} in @code{wdiff}. 1278 1279@item no-dereference 1280@samp{-d} in @code{cp}. 1281 1282@item no-inserted 1283@samp{-2} in @code{wdiff}. 1284 1285@item no-keep-going 1286@samp{-S} in Make. 1287 1288@item no-lines 1289@samp{-l} in Bison. 1290 1291@item no-piping 1292@samp{-P} in @code{shar}. 1293 1294@item no-prof 1295@samp{-e} in @code{gprof}. 1296 1297@item no-regex 1298@samp{-R} in @code{etags}. 1299 1300@item no-sort 1301@samp{-p} in @code{nm}. 1302 1303@item no-split 1304Used in @code{makeinfo}. 1305 1306@item no-static 1307@samp{-a} in @code{gprof}. 1308 1309@item no-time 1310@samp{-E} in @code{gprof}. 1311 1312@item no-timestamp 1313@samp{-m} in @code{shar}. 1314 1315@item no-validate 1316Used in @code{makeinfo}. 1317 1318@item no-wait 1319Used in @code{emacsclient}. 1320 1321@item no-warn 1322Used in various programs to inhibit warnings. 1323 1324@item node 1325@samp{-n} in @code{info}. 1326 1327@item nodename 1328@samp{-n} in @code{uname}. 1329 1330@item nonmatching 1331@samp{-f} in @code{cpio}. 1332 1333@item nstuff 1334@samp{-n} in @code{objdump}. 1335 1336@item null 1337@samp{-0} in @code{xargs}. 1338 1339@item number 1340@samp{-n} in @code{cat}. 1341 1342@item number-nonblank 1343@samp{-b} in @code{cat}. 1344 1345@item numeric-sort 1346@samp{-n} in @code{nm}. 1347 1348@item numeric-uid-gid 1349@samp{-n} in @code{cpio} and @code{ls}. 1350 1351@item nx 1352Used in GDB. 1353 1354@item old-archive 1355@samp{-o} in @code{tar}. 1356 1357@item old-file 1358@samp{-o} in Make. 1359 1360@item one-file-system 1361@samp{-l} in @code{tar}, @code{cp}, and @code{du}. 1362 1363@item only-file 1364@samp{-o} in @code{ptx}. 1365 1366@item only-prof 1367@samp{-f} in @code{gprof}. 1368 1369@item only-time 1370@samp{-F} in @code{gprof}. 1371 1372@item output 1373In various programs, specify the output file name. 1374 1375@item output-prefix 1376@samp{-o} in @code{shar}. 1377 1378@item override 1379@samp{-o} in @code{rm}. 1380 1381@item overwrite 1382@samp{-c} in @code{unshar}. 1383 1384@item owner 1385@samp{-o} in @code{install}. 1386 1387@item paginate 1388@samp{-l} in @code{diff}. 1389 1390@item paragraph-indent 1391Used in @code{makeinfo}. 1392 1393@item parents 1394@samp{-p} in @code{mkdir} and @code{rmdir}. 1395 1396@item pass-all 1397@samp{-p} in @code{ul}. 1398 1399@item pass-through 1400@samp{-p} in @code{cpio}. 1401 1402@item port 1403@samp{-P} in @code{finger}. 1404 1405@item portability 1406@samp{-c} in @code{cpio} and @code{tar}. 1407 1408@item posix 1409Used in @code{gawk}. 1410 1411@item prefix-builtins 1412@samp{-P} in @code{m4}. 1413 1414@item prefix 1415@samp{-f} in @code{csplit}. 1416 1417@item preserve 1418Used in @code{tar} and @code{cp}. 1419 1420@item preserve-environment 1421@samp{-p} in @code{su}. 1422 1423@item preserve-modification-time 1424@samp{-m} in @code{cpio}. 1425 1426@item preserve-order 1427@samp{-s} in @code{tar}. 1428 1429@item preserve-permissions 1430@samp{-p} in @code{tar}. 1431 1432@item print 1433@samp{-l} in @code{diff}. 1434 1435@item print-chars 1436@samp{-L} in @code{cmp}. 1437 1438@item print-data-base 1439@samp{-p} in Make. 1440 1441@item print-directory 1442@samp{-w} in Make. 1443 1444@item print-file-name 1445@samp{-o} in @code{nm}. 1446 1447@item print-symdefs 1448@samp{-s} in @code{nm}. 1449 1450@item printer 1451@samp{-p} in @code{wdiff}. 1452 1453@item prompt 1454@samp{-p} in @code{ed}. 1455 1456@item query-user 1457@samp{-X} in @code{shar}. 1458 1459@item question 1460@samp{-q} in Make. 1461 1462@item quiet 1463Used in many programs to inhibit the usual output. @strong{Note:} every 1464program accepting @samp{--quiet} should accept @samp{--silent} as a 1465synonym. 1466 1467@item quiet-unshar 1468@samp{-Q} in @code{shar} 1469 1470@item quote-name 1471@samp{-Q} in @code{ls}. 1472 1473@item rcs 1474@samp{-n} in @code{diff}. 1475 1476@item re-interval 1477Used in @code{gawk}. 1478 1479@item read-full-blocks 1480@samp{-B} in @code{tar}. 1481 1482@item readnow 1483Used in GDB. 1484 1485@item recon 1486@samp{-n} in Make. 1487 1488@item record-number 1489@samp{-R} in @code{tar}. 1490 1491@item recursive 1492Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, 1493and @code{rm}. 1494 1495@item reference-limit 1496Used in @code{makeinfo}. 1497 1498@item references 1499@samp{-r} in @code{ptx}. 1500 1501@item regex 1502@samp{-r} in @code{tac} and @code{etags}. 1503 1504@item release 1505@samp{-r} in @code{uname}. 1506 1507@item reload-state 1508@samp{-R} in @code{m4}. 1509 1510@item relocation 1511@samp{-r} in @code{objdump}. 1512 1513@item rename 1514@samp{-r} in @code{cpio}. 1515 1516@item replace 1517@samp{-i} in @code{xargs}. 1518 1519@item report-identical-files 1520@samp{-s} in @code{diff}. 1521 1522@item reset-access-time 1523@samp{-a} in @code{cpio}. 1524 1525@item reverse 1526@samp{-r} in @code{ls} and @code{nm}. 1527 1528@item reversed-ed 1529@samp{-f} in @code{diff}. 1530 1531@item right-side-defs 1532@samp{-R} in @code{ptx}. 1533 1534@item same-order 1535@samp{-s} in @code{tar}. 1536 1537@item same-permissions 1538@samp{-p} in @code{tar}. 1539 1540@item save 1541@samp{-g} in @code{stty}. 1542 1543@item se 1544Used in GDB. 1545 1546@item sentence-regexp 1547@samp{-S} in @code{ptx}. 1548 1549@item separate-dirs 1550@samp{-S} in @code{du}. 1551 1552@item separator 1553@samp{-s} in @code{tac}. 1554 1555@item sequence 1556Used by @code{recode} to chose files or pipes for sequencing passes. 1557 1558@item shell 1559@samp{-s} in @code{su}. 1560 1561@item show-all 1562@samp{-A} in @code{cat}. 1563 1564@item show-c-function 1565@samp{-p} in @code{diff}. 1566 1567@item show-ends 1568@samp{-E} in @code{cat}. 1569 1570@item show-function-line 1571@samp{-F} in @code{diff}. 1572 1573@item show-tabs 1574@samp{-T} in @code{cat}. 1575 1576@item silent 1577Used in many programs to inhibit the usual output. 1578@strong{Note:} every program accepting 1579@samp{--silent} should accept @samp{--quiet} as a synonym. 1580 1581@item size 1582@samp{-s} in @code{ls}. 1583 1584@item socket 1585Specify a file descriptor for a network server to use for its socket, 1586instead of opening and binding a new socket. This provides a way to 1587run, in a nonpriveledged process, a server that normally needs a 1588reserved port number. 1589 1590@item sort 1591Used in @code{ls}. 1592 1593@item source 1594@samp{-W source} in @code{gawk}. 1595 1596@item sparse 1597@samp{-S} in @code{tar}. 1598 1599@item speed-large-files 1600@samp{-H} in @code{diff}. 1601 1602@item split-at 1603@samp{-E} in @code{unshar}. 1604 1605@item split-size-limit 1606@samp{-L} in @code{shar}. 1607 1608@item squeeze-blank 1609@samp{-s} in @code{cat}. 1610 1611@item start-delete 1612@samp{-w} in @code{wdiff}. 1613 1614@item start-insert 1615@samp{-y} in @code{wdiff}. 1616 1617@item starting-file 1618Used in @code{tar} and @code{diff} to specify which file within 1619a directory to start processing with. 1620 1621@item statistics 1622@samp{-s} in @code{wdiff}. 1623 1624@item stdin-file-list 1625@samp{-S} in @code{shar}. 1626 1627@item stop 1628@samp{-S} in Make. 1629 1630@item strict 1631@samp{-s} in @code{recode}. 1632 1633@item strip 1634@samp{-s} in @code{install}. 1635 1636@item strip-all 1637@samp{-s} in @code{strip}. 1638 1639@item strip-debug 1640@samp{-S} in @code{strip}. 1641 1642@item submitter 1643@samp{-s} in @code{shar}. 1644 1645@item suffix 1646@samp{-S} in @code{cp}, @code{ln}, @code{mv}. 1647 1648@item suffix-format 1649@samp{-b} in @code{csplit}. 1650 1651@item sum 1652@samp{-s} in @code{gprof}. 1653 1654@item summarize 1655@samp{-s} in @code{du}. 1656 1657@item symbolic 1658@samp{-s} in @code{ln}. 1659 1660@item symbols 1661Used in GDB and @code{objdump}. 1662 1663@item synclines 1664@samp{-s} in @code{m4}. 1665 1666@item sysname 1667@samp{-s} in @code{uname}. 1668 1669@item tabs 1670@samp{-t} in @code{expand} and @code{unexpand}. 1671 1672@item tabsize 1673@samp{-T} in @code{ls}. 1674 1675@item terminal 1676@samp{-T} in @code{tput} and @code{ul}. 1677@samp{-t} in @code{wdiff}. 1678 1679@item text 1680@samp{-a} in @code{diff}. 1681 1682@item text-files 1683@samp{-T} in @code{shar}. 1684 1685@item time 1686Used in @code{ls} and @code{touch}. 1687 1688@item to-stdout 1689@samp{-O} in @code{tar}. 1690 1691@item total 1692@samp{-c} in @code{du}. 1693 1694@item touch 1695@samp{-t} in Make, @code{ranlib}, and @code{recode}. 1696 1697@item trace 1698@samp{-t} in @code{m4}. 1699 1700@item traditional 1701@samp{-t} in @code{hello}; 1702@samp{-W traditional} in @code{gawk}; 1703@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. 1704 1705@item tty 1706Used in GDB. 1707 1708@item typedefs 1709@samp{-t} in @code{ctags}. 1710 1711@item typedefs-and-c++ 1712@samp{-T} in @code{ctags}. 1713 1714@item typeset-mode 1715@samp{-t} in @code{ptx}. 1716 1717@item uncompress 1718@samp{-z} in @code{tar}. 1719 1720@item unconditional 1721@samp{-u} in @code{cpio}. 1722 1723@item undefine 1724@samp{-U} in @code{m4}. 1725 1726@item undefined-only 1727@samp{-u} in @code{nm}. 1728 1729@item update 1730@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. 1731 1732@item usage 1733Used in @code{gawk}; same as @samp{--help}. 1734 1735@item uuencode 1736@samp{-B} in @code{shar}. 1737 1738@item vanilla-operation 1739@samp{-V} in @code{shar}. 1740 1741@item verbose 1742Print more information about progress. Many programs support this. 1743 1744@item verify 1745@samp{-W} in @code{tar}. 1746 1747@item version 1748Print the version number. 1749 1750@item version-control 1751@samp{-V} in @code{cp}, @code{ln}, @code{mv}. 1752 1753@item vgrind 1754@samp{-v} in @code{ctags}. 1755 1756@item volume 1757@samp{-V} in @code{tar}. 1758 1759@item what-if 1760@samp{-W} in Make. 1761 1762@item whole-size-limit 1763@samp{-l} in @code{shar}. 1764 1765@item width 1766@samp{-w} in @code{ls} and @code{ptx}. 1767 1768@item word-regexp 1769@samp{-W} in @code{ptx}. 1770 1771@item writable 1772@samp{-T} in @code{who}. 1773 1774@item zeros 1775@samp{-z} in @code{gprof}. 1776@end table 1777 1778@node Memory Usage 1779@section Memory Usage 1780 1781If it typically uses just a few meg of memory, don't bother making any 1782effort to reduce memory usage. For example, if it is impractical for 1783other reasons to operate on files more than a few meg long, it is 1784reasonable to read entire input files into core to operate on them. 1785 1786However, for programs such as @code{cat} or @code{tail}, that can 1787usefully operate on very large files, it is important to avoid using a 1788technique that would artificially limit the size of files it can handle. 1789If a program works by lines and could be applied to arbitrary 1790user-supplied input files, it should keep only a line in memory, because 1791this is not very hard and users will want to be able to operate on input 1792files that are bigger than will fit in core all at once. 1793 1794If your program creates complicated data structures, just make them in 1795core and give a fatal error if @code{malloc} returns zero. 1796 1797@node Writing C 1798@chapter Making The Best Use of C 1799 1800This @value{CHAPTER} provides advice on how best to use the C language 1801when writing GNU software. 1802 1803@menu 1804* Formatting:: Formatting Your Source Code 1805* Comments:: Commenting Your Work 1806* Syntactic Conventions:: Clean Use of C Constructs 1807* Names:: Naming Variables and Functions 1808* System Portability:: Portability between different operating systems 1809* CPU Portability:: Supporting the range of CPU types 1810* System Functions:: Portability and ``standard'' library functions 1811* Internationalization:: Techniques for internationalization 1812* Mmap:: How you can safely use @code{mmap}. 1813@end menu 1814 1815@node Formatting 1816@section Formatting Your Source Code 1817 1818It is important to put the open-brace that starts the body of a C 1819function in column zero, and avoid putting any other open-brace or 1820open-parenthesis or open-bracket in column zero. Several tools look 1821for open-braces in column zero to find the beginnings of C functions. 1822These tools will not work on code not formatted that way. 1823 1824It is also important for function definitions to start the name of the 1825function in column zero. This helps people to search for function 1826definitions, and may also help certain tools recognize them. Thus, 1827the proper format is this: 1828 1829@example 1830static char * 1831concat (s1, s2) /* Name starts in column zero here */ 1832 char *s1, *s2; 1833@{ /* Open brace in column zero here */ 1834 @dots{} 1835@} 1836@end example 1837 1838@noindent 1839or, if you want to use @sc{ansi} C, format the definition like this: 1840 1841@example 1842static char * 1843concat (char *s1, char *s2) 1844@{ 1845 @dots{} 1846@} 1847@end example 1848 1849In @sc{ansi} C, if the arguments don't fit nicely on one line, 1850split it like this: 1851 1852@example 1853int 1854lots_of_args (int an_integer, long a_long, short a_short, 1855 double a_double, float a_float) 1856@dots{} 1857@end example 1858 1859For the body of the function, we prefer code formatted like this: 1860 1861@example 1862if (x < foo (y, z)) 1863 haha = bar[4] + 5; 1864else 1865 @{ 1866 while (z) 1867 @{ 1868 haha += foo (z, z); 1869 z--; 1870 @} 1871 return ++x + bar (); 1872 @} 1873@end example 1874 1875We find it easier to read a program when it has spaces before the 1876open-parentheses and after the commas. Especially after the commas. 1877 1878When you split an expression into multiple lines, split it 1879before an operator, not after one. Here is the right way: 1880 1881@example 1882if (foo_this_is_long && bar > win (x, y, z) 1883 && remaining_condition) 1884@end example 1885 1886Try to avoid having two operators of different precedence at the same 1887level of indentation. For example, don't write this: 1888 1889@example 1890mode = (inmode[j] == VOIDmode 1891 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) 1892 ? outmode[j] : inmode[j]); 1893@end example 1894 1895Instead, use extra parentheses so that the indentation shows the nesting: 1896 1897@example 1898mode = ((inmode[j] == VOIDmode 1899 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) 1900 ? outmode[j] : inmode[j]); 1901@end example 1902 1903Insert extra parentheses so that Emacs will indent the code properly. 1904For example, the following indentation looks nice if you do it by hand, 1905but Emacs would mess it up: 1906 1907@example 1908v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 1909 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; 1910@end example 1911 1912But adding a set of parentheses solves the problem: 1913 1914@example 1915v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 1916 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); 1917@end example 1918 1919Format do-while statements like this: 1920 1921@example 1922do 1923 @{ 1924 a = foo (a); 1925 @} 1926while (a > 0); 1927@end example 1928 1929Please use formfeed characters (control-L) to divide the program into 1930pages at logical places (but not within a function). It does not matter 1931just how long the pages are, since they do not have to fit on a printed 1932page. The formfeeds should appear alone on lines by themselves. 1933 1934 1935@node Comments 1936@section Commenting Your Work 1937 1938Every program should start with a comment saying briefly what it is for. 1939Example: @samp{fmt - filter for simple filling of text}. 1940 1941Please write the comments in a GNU program in English, because English 1942is the one language that nearly all programmers in all countries can 1943read. If you do not write English well, please write comments in 1944English as well as you can, then ask other people to help rewrite them. 1945If you can't write comments in English, please find someone to work with 1946you and translate your comments into English. 1947 1948Please put a comment on each function saying what the function does, 1949what sorts of arguments it gets, and what the possible values of 1950arguments mean and are used for. It is not necessary to duplicate in 1951words the meaning of the C argument declarations, if a C type is being 1952used in its customary fashion. If there is anything nonstandard about 1953its use (such as an argument of type @code{char *} which is really the 1954address of the second character of a string, not the first), or any 1955possible values that would not work the way one would expect (such as, 1956that strings containing newlines are not guaranteed to work), be sure 1957to say so. 1958 1959Also explain the significance of the return value, if there is one. 1960 1961Please put two spaces after the end of a sentence in your comments, so 1962that the Emacs sentence commands will work. Also, please write 1963complete sentences and capitalize the first word. If a lower-case 1964identifier comes at the beginning of a sentence, don't capitalize it! 1965Changing the spelling makes it a different identifier. If you don't 1966like starting a sentence with a lower case letter, write the sentence 1967differently (e.g., ``The identifier lower-case is @dots{}''). 1968 1969The comment on a function is much clearer if you use the argument 1970names to speak about the argument values. The variable name itself 1971should be lower case, but write it in upper case when you are speaking 1972about the value rather than the variable itself. Thus, ``the inode 1973number NODE_NUM'' rather than ``an inode''. 1974 1975There is usually no purpose in restating the name of the function in 1976the comment before it, because the reader can see that for himself. 1977There might be an exception when the comment is so long that the function 1978itself would be off the bottom of the screen. 1979 1980There should be a comment on each static variable as well, like this: 1981 1982@example 1983/* Nonzero means truncate lines in the display; 1984 zero means continue them. */ 1985int truncate_lines; 1986@end example 1987 1988Every @samp{#endif} should have a comment, except in the case of short 1989conditionals (just a few lines) that are not nested. The comment should 1990state the condition of the conditional that is ending, @emph{including 1991its sense}. @samp{#else} should have a comment describing the condition 1992@emph{and sense} of the code that follows. For example: 1993 1994@example 1995@group 1996#ifdef foo 1997 @dots{} 1998#else /* not foo */ 1999 @dots{} 2000#endif /* not foo */ 2001@end group 2002@group 2003#ifdef foo 2004 @dots{} 2005#endif /* foo */ 2006@end group 2007@end example 2008 2009@noindent 2010but, by contrast, write the comments this way for a @samp{#ifndef}: 2011 2012@example 2013@group 2014#ifndef foo 2015 @dots{} 2016#else /* foo */ 2017 @dots{} 2018#endif /* foo */ 2019@end group 2020@group 2021#ifndef foo 2022 @dots{} 2023#endif /* not foo */ 2024@end group 2025@end example 2026 2027@node Syntactic Conventions 2028@section Clean Use of C Constructs 2029 2030Please explicitly declare all arguments to functions. 2031Don't omit them just because they are @code{int}s. 2032 2033Declarations of external functions and functions to appear later in the 2034source file should all go in one place near the beginning of the file 2035(somewhere before the first function definition in the file), or else 2036should go in a header file. Don't put @code{extern} declarations inside 2037functions. 2038 2039It used to be common practice to use the same local variables (with 2040names like @code{tem}) over and over for different values within one 2041function. Instead of doing this, it is better declare a separate local 2042variable for each distinct purpose, and give it a name which is 2043meaningful. This not only makes programs easier to understand, it also 2044facilitates optimization by good compilers. You can also move the 2045declaration of each local variable into the smallest scope that includes 2046all its uses. This makes the program even cleaner. 2047 2048Don't use local variables or parameters that shadow global identifiers. 2049 2050Don't declare multiple variables in one declaration that spans lines. 2051Start a new declaration on each line, instead. For example, instead 2052of this: 2053 2054@example 2055@group 2056int foo, 2057 bar; 2058@end group 2059@end example 2060 2061@noindent 2062write either this: 2063 2064@example 2065int foo, bar; 2066@end example 2067 2068@noindent 2069or this: 2070 2071@example 2072int foo; 2073int bar; 2074@end example 2075 2076@noindent 2077(If they are global variables, each should have a comment preceding it 2078anyway.) 2079 2080When you have an @code{if}-@code{else} statement nested in another 2081@code{if} statement, always put braces around the @code{if}-@code{else}. 2082Thus, never write like this: 2083 2084@example 2085if (foo) 2086 if (bar) 2087 win (); 2088 else 2089 lose (); 2090@end example 2091 2092@noindent 2093always like this: 2094 2095@example 2096if (foo) 2097 @{ 2098 if (bar) 2099 win (); 2100 else 2101 lose (); 2102 @} 2103@end example 2104 2105If you have an @code{if} statement nested inside of an @code{else} 2106statement, either write @code{else if} on one line, like this, 2107 2108@example 2109if (foo) 2110 @dots{} 2111else if (bar) 2112 @dots{} 2113@end example 2114 2115@noindent 2116with its @code{then}-part indented like the preceding @code{then}-part, 2117or write the nested @code{if} within braces like this: 2118 2119@example 2120if (foo) 2121 @dots{} 2122else 2123 @{ 2124 if (bar) 2125 @dots{} 2126 @} 2127@end example 2128 2129Don't declare both a structure tag and variables or typedefs in the 2130same declaration. Instead, declare the structure tag separately 2131and then use it to declare the variables or typedefs. 2132 2133Try to avoid assignments inside @code{if}-conditions. For example, 2134don't write this: 2135 2136@example 2137if ((foo = (char *) malloc (sizeof *foo)) == 0) 2138 fatal ("virtual memory exhausted"); 2139@end example 2140 2141@noindent 2142instead, write this: 2143 2144@example 2145foo = (char *) malloc (sizeof *foo); 2146if (foo == 0) 2147 fatal ("virtual memory exhausted"); 2148@end example 2149 2150Don't make the program ugly to placate @code{lint}. Please don't insert any 2151casts to @code{void}. Zero without a cast is perfectly fine as a null 2152pointer constant, except when calling a varargs function. 2153 2154@node Names 2155@section Naming Variables and Functions 2156 2157The names of global variables and functions in a program serve as 2158comments of a sort. So don't choose terse names---instead, look for 2159names that give useful information about the meaning of the variable or 2160function. In a GNU program, names should be English, like other 2161comments. 2162 2163Local variable names can be shorter, because they are used only within 2164one context, where (presumably) comments explain their purpose. 2165 2166Please use underscores to separate words in a name, so that the Emacs 2167word commands can be useful within them. Stick to lower case; reserve 2168upper case for macros and @code{enum} constants, and for name-prefixes 2169that follow a uniform convention. 2170 2171For example, you should use names like @code{ignore_space_change_flag}; 2172don't use names like @code{iCantReadThis}. 2173 2174Variables that indicate whether command-line options have been 2175specified should be named after the meaning of the option, not after 2176the option-letter. A comment should state both the exact meaning of 2177the option and its letter. For example, 2178 2179@example 2180@group 2181/* Ignore changes in horizontal whitespace (-b). */ 2182int ignore_space_change_flag; 2183@end group 2184@end example 2185 2186When you want to define names with constant integer values, use 2187@code{enum} rather than @samp{#define}. GDB knows about enumeration 2188constants. 2189 2190Use file names of 14 characters or less, to avoid creating gratuitous 2191problems on older System V systems. You can use the program 2192@code{doschk} to test for this. @code{doschk} also tests for potential 2193name conflicts if the files were loaded onto an MS-DOS file 2194system---something you may or may not care about. 2195 2196@node System Portability 2197@section Portability between System Types 2198 2199In the Unix world, ``portability'' refers to porting to different Unix 2200versions. For a GNU program, this kind of portability is desirable, but 2201not paramount. 2202 2203The primary purpose of GNU software is to run on top of the GNU kernel, 2204compiled with the GNU C compiler, on various types of @sc{cpu}. The 2205amount and kinds of variation among GNU systems on different @sc{cpu}s 2206will be comparable to the variation among Linux-based GNU systems or 2207among BSD systems today. So the kinds of portability that are absolutely 2208necessary are quite limited. 2209 2210But many users do run GNU software on non-GNU Unix or Unix-like systems. 2211So supporting a variety of Unix-like systems is desirable, although not 2212paramount. 2213 2214The easiest way to achieve portability to most Unix-like systems is to 2215use Autoconf. It's unlikely that your program needs to know more 2216information about the host platform than Autoconf can provide, simply 2217because most of the programs that need such knowledge have already been 2218written. 2219 2220Avoid using the format of semi-internal data bases (e.g., directories) 2221when there is a higher-level alternative (@code{readdir}). 2222 2223As for systems that are not like Unix, such as MSDOS, Windows, the 2224Macintosh, VMS, and MVS, supporting them is usually so much work that it 2225is better if you don't. 2226 2227The planned GNU kernel is not finished yet, but you can tell which 2228facilities it will provide by looking at the GNU C Library Manual. The 2229GNU kernel is based on Mach, so the features of Mach will also be 2230available. However, if you use Mach features, you'll probably have 2231trouble debugging your program today. 2232 2233@node CPU Portability 2234@section Portability between @sc{cpu}s 2235 2236Even GNU systems will differ because of differences among @sc{cpu} 2237types---for example, difference in byte ordering and alignment 2238requirements. It is absolutely essential to handle these differences. 2239However, don't make any effort to cater to the possibility that an 2240@code{int} will be less than 32 bits. We don't support 16-bit machines 2241in GNU. 2242 2243Don't assume that the address of an @code{int} object is also the 2244address of its least-significant byte. This is false on big-endian 2245machines. Thus, don't make the following mistake: 2246 2247@example 2248int c; 2249@dots{} 2250while ((c = getchar()) != EOF) 2251 write(file_descriptor, &c, 1); 2252@end example 2253 2254When calling functions, you need not worry about the difference between 2255pointers of various types, or between pointers and integers. On most 2256machines, there's no difference anyway. As for the few machines where 2257there is a difference, all of them support @sc{ansi} C, so you can use 2258prototypes (conditionalized to be active only in @sc{ansi} C) to make 2259the code work on those systems. 2260 2261In certain cases, it is ok to pass integer and pointer arguments 2262indiscriminately to the same function, and use no prototype on any 2263system. For example, many GNU programs have error-reporting functions 2264that pass their arguments along to @code{printf} and friends: 2265 2266@example 2267error (s, a1, a2, a3) 2268 char *s; 2269 int a1, a2, a3; 2270@{ 2271 fprintf (stderr, "error: "); 2272 fprintf (stderr, s, a1, a2, a3); 2273@} 2274@end example 2275 2276@noindent 2277In practice, this works on all machines, and it is much simpler than any 2278``correct'' alternative. Be sure @emph{not} to use a prototype 2279for such functions. 2280 2281However, avoid casting pointers to integers unless you really need to. 2282These assumptions really reduce portability, and in most programs they 2283are easy to avoid. In the cases where casting pointers to integers is 2284essential---such as, a Lisp interpreter which stores type information as 2285well as an address in one word---it is ok to do so, but you'll have to 2286make explicit provisions to handle different word sizes. 2287 2288@node System Functions 2289@section Calling System Functions 2290 2291C implementations differ substantially. @sc{ansi} C reduces but does not 2292eliminate the incompatibilities; meanwhile, many users wish to compile 2293GNU software with pre-@sc{ansi} compilers. This chapter gives 2294recommendations for how to use the more or less standard C library 2295functions to avoid unnecessary loss of portability. 2296 2297@itemize @bullet 2298@item 2299Don't use the value of @code{sprintf}. It returns the number of 2300characters written on some systems, but not on all systems. 2301 2302@item 2303@code{main} should be declared to return type @code{int}. It should 2304terminate either by calling @code{exit} or by returning the integer 2305status code; make sure it cannot ever return an undefined value. 2306 2307@item 2308Don't declare system functions explicitly. 2309 2310Almost any declaration for a system function is wrong on some system. 2311To minimize conflicts, leave it to the system header files to declare 2312system functions. If the headers don't declare a function, let it 2313remain undeclared. 2314 2315While it may seem unclean to use a function without declaring it, in 2316practice this works fine for most system library functions on the 2317systems where this really happens; thus, the disadvantage is only 2318theoretical. By contrast, actual declarations have frequently caused 2319actual conflicts. 2320 2321@item 2322If you must declare a system function, don't specify the argument types. 2323Use an old-style declaration, not an @sc{ansi} prototype. The more you 2324specify about the function, the more likely a conflict. 2325 2326@item 2327In particular, don't unconditionally declare @code{malloc} or 2328@code{realloc}. 2329 2330Most GNU programs use those functions just once, in functions 2331conventionally named @code{xmalloc} and @code{xrealloc}. These 2332functions call @code{malloc} and @code{realloc}, respectively, and 2333check the results. 2334 2335Because @code{xmalloc} and @code{xrealloc} are defined in your program, 2336you can declare them in other files without any risk of type conflict. 2337 2338On most systems, @code{int} is the same length as a pointer; thus, the 2339calls to @code{malloc} and @code{realloc} work fine. For the few 2340exceptional systems (mostly 64-bit machines), you can use 2341@strong{conditionalized} declarations of @code{malloc} and 2342@code{realloc}---or put these declarations in configuration files 2343specific to those systems. 2344 2345@item 2346The string functions require special treatment. Some Unix systems have 2347a header file @file{string.h}; others have @file{strings.h}. Neither 2348file name is portable. There are two things you can do: use Autoconf to 2349figure out which file to include, or don't include either file. 2350 2351@item 2352If you don't include either strings file, you can't get declarations for 2353the string functions from the header file in the usual way. 2354 2355That causes less of a problem than you might think. The newer @sc{ansi} 2356string functions should be avoided anyway because many systems still 2357don't support them. The string functions you can use are these: 2358 2359@example 2360strcpy strncpy strcat strncat 2361strlen strcmp strncmp 2362strchr strrchr 2363@end example 2364 2365The copy and concatenate functions work fine without a declaration as 2366long as you don't use their values. Using their values without a 2367declaration fails on systems where the width of a pointer differs from 2368the width of @code{int}, and perhaps in other cases. It is trivial to 2369avoid using their values, so do that. 2370 2371The compare functions and @code{strlen} work fine without a declaration 2372on most systems, possibly all the ones that GNU software runs on. 2373You may find it necessary to declare them @strong{conditionally} on a 2374few systems. 2375 2376The search functions must be declared to return @code{char *}. Luckily, 2377there is no variation in the data type they return. But there is 2378variation in their names. Some systems give these functions the names 2379@code{index} and @code{rindex}; other systems use the names 2380@code{strchr} and @code{strrchr}. Some systems support both pairs of 2381names, but neither pair works on all systems. 2382 2383You should pick a single pair of names and use it throughout your 2384program. (Nowadays, it is better to choose @code{strchr} and 2385@code{strrchr} for new programs, since those are the standard @sc{ansi} 2386names.) Declare both of those names as functions returning @code{char 2387*}. On systems which don't support those names, define them as macros 2388in terms of the other pair. For example, here is what to put at the 2389beginning of your file (or in a header) if you want to use the names 2390@code{strchr} and @code{strrchr} throughout: 2391 2392@example 2393#ifndef HAVE_STRCHR 2394#define strchr index 2395#endif 2396#ifndef HAVE_STRRCHR 2397#define strrchr rindex 2398#endif 2399 2400char *strchr (); 2401char *strrchr (); 2402@end example 2403@end itemize 2404 2405Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are 2406macros defined in systems where the corresponding functions exist. 2407One way to get them properly defined is to use Autoconf. 2408 2409@node Internationalization 2410@section Internationalization 2411 2412GNU has a library called GNU gettext that makes it easy to translate the 2413messages in a program into various languages. You should use this 2414library in every program. Use English for the messages as they appear 2415in the program, and let gettext provide the way to translate them into 2416other languages. 2417 2418Using GNU gettext involves putting a call to the @code{gettext} macro 2419around each string that might need translation---like this: 2420 2421@example 2422printf (gettext ("Processing file `%s'...")); 2423@end example 2424 2425@noindent 2426This permits GNU gettext to replace the string @code{"Processing file 2427`%s'..."} with a translated version. 2428 2429Once a program uses gettext, please make a point of writing calls to 2430@code{gettext} when you add new strings that call for translation. 2431 2432Using GNU gettext in a package involves specifying a @dfn{text domain 2433name} for the package. The text domain name is used to separate the 2434translations for this package from the translations for other packages. 2435Normally, the text domain name should be the same as the name of the 2436package---for example, @samp{fileutils} for the GNU file utilities. 2437 2438To enable gettext to work well, avoid writing code that makes 2439assumptions about the structure of words or sentences. When you want 2440the precise text of a sentence to vary depending on the data, use two or 2441more alternative string constants each containing a complete sentences, 2442rather than inserting conditionalized words or phrases into a single 2443sentence framework. 2444 2445Here is an example of what not to do: 2446 2447@example 2448printf ("%d file%s processed", nfiles, 2449 nfiles != 1 ? "s" : ""); 2450@end example 2451 2452@noindent 2453The problem with that example is that it assumes that plurals are made 2454by adding `s'. If you apply gettext to the format string, like this, 2455 2456@example 2457printf (gettext ("%d file%s processed"), nfiles, 2458 nfiles != 1 ? "s" : ""); 2459@end example 2460 2461@noindent 2462the message can use different words, but it will still be forced to use 2463`s' for the plural. Here is a better way: 2464 2465@example 2466printf ((nfiles != 1 ? "%d files processed" 2467 : "%d file processed"), 2468 nfiles); 2469@end example 2470 2471@noindent 2472This way, you can apply gettext to each of the two strings 2473independently: 2474 2475@example 2476printf ((nfiles != 1 ? gettext ("%d files processed") 2477 : gettext ("%d file processed")), 2478 nfiles); 2479@end example 2480 2481@noindent 2482This can be any method of forming the plural of the word for ``file'', and 2483also handles languages that require agreement in the word for 2484``processed''. 2485 2486A similar problem appears at the level of sentence structure with this 2487code: 2488 2489@example 2490printf ("# Implicit rule search has%s been done.\n", 2491 f->tried_implicit ? "" : " not"); 2492@end example 2493 2494@noindent 2495Adding @code{gettext} calls to this code cannot give correct results for 2496all languages, because negation in some languages requires adding words 2497at more than one place in the sentence. By contrast, adding 2498@code{gettext} calls does the job straightfowardly if the code starts 2499out like this: 2500 2501@example 2502printf (f->tried_implicit 2503 ? "# Implicit rule search has been done.\n", 2504 : "# Implicit rule search has not been done.\n"); 2505@end example 2506 2507@node Mmap 2508@section Mmap 2509 2510Don't assume that @code{mmap} either works on all files or fails 2511for all files. It may work on some files and fail on others. 2512 2513The proper way to use @code{mmap} is to try it on the specific file for 2514which you want to use it---and if @code{mmap} doesn't work, fall back on 2515doing the job in another way using @code{read} and @code{write}. 2516 2517The reason this precaution is needed is that the GNU kernel (the HURD) 2518provides a user-extensible file system, in which there can be many 2519different kinds of ``ordinary files.'' Many of them support 2520@code{mmap}, but some do not. It is important to make programs handle 2521all these kinds of files. 2522 2523@node Documentation 2524@chapter Documenting Programs 2525 2526@menu 2527* GNU Manuals:: Writing proper manuals. 2528* Manual Structure Details:: Specific structure conventions. 2529* NEWS File:: NEWS files supplement manuals. 2530* Change Logs:: Recording Changes 2531* Man Pages:: Man pages are secondary. 2532* Reading other Manuals:: How far you can go in learning 2533 from other manuals. 2534@end menu 2535 2536@node GNU Manuals 2537@section GNU Manuals 2538 2539The preferred way to document part of the GNU system is to write a 2540manual in the Texinfo formatting language. See the Texinfo manual, 2541either the hardcopy, or the on-line version available through 2542@code{info} or the Emacs Info subsystem (@kbd{C-h i}). 2543 2544Programmers often find it most natural to structure the documentation 2545following the structure of the implementation, which they know. But 2546this structure is not necessarily good for explaining how to use the 2547program; it may be irrelevant and confusing for a user. 2548 2549At every level, from the sentences in a paragraph to the grouping of 2550topics into separate manuals, the right way to structure documentation 2551is according to the concepts and questions that a user will have in mind 2552when reading it. Sometimes this structure of ideas matches the 2553structure of the implementation of the software being documented---but 2554often they are different. Often the most important part of learning to 2555write good documentation is learning to notice when you are structuring 2556the documentation like the implementation, and think about better 2557alternatives. 2558 2559For example, each program in the GNU system probably ought to be 2560documented in one manual; but this does not mean each program should 2561have its own manual. That would be following the structure of the 2562implementation, rather than the structure that helps the user 2563understand. 2564 2565Instead, each manual should cover a coherent @emph{topic}. For example, 2566instead of a manual for @code{diff} and a manual for @code{diff3}, we 2567have one manual for ``comparison of files'' which covers both of those 2568programs, as well as @code{cmp}. By documenting these programs 2569together, we can make the whole subject clearer. 2570 2571The manual which discusses a program should document all of the 2572program's command-line options and all of its commands. It should give 2573examples of their use. But don't organize the manual as a list of 2574features. Instead, organize it logically, by subtopics. Address the 2575questions that a user will ask when thinking about the job that the 2576program does. 2577 2578In general, a GNU manual should serve both as tutorial and reference. 2579It should be set up for convenient access to each topic through Info, 2580and for reading straight through (appendixes aside). A GNU manual 2581should give a good introduction to a beginner reading through from the 2582start, and should also provide all the details that hackers want. 2583 2584That is not as hard as it first sounds. Arrange each chapter as a 2585logical breakdown of its topic, but order the sections, and write their 2586text, so that reading the chapter straight through makes sense. Do 2587likewise when structuring the book into chapters, and when structuring a 2588section into paragraphs. The watchword is, @emph{at each point, address 2589the most fundamental and important issue raised by the preceding text.} 2590 2591If necessary, add extra chapters at the beginning of the manual which 2592are purely tutorial and cover the basics of the subject. These provide 2593the framework for a beginner to understand the rest of the manual. The 2594Bison manual provides a good example of how to do this. 2595 2596Don't use Unix man pages as a model for how to write GNU documentation; 2597most of them are terse, badly structured, and give inadequate 2598explanation of the underlying concepts. (There are, of course 2599exceptions.) Also Unix man pages use a particular format which is 2600different from what we use in GNU manuals. 2601 2602Please do not use the term ``pathname'' that is used in Unix 2603documentation; use ``file name'' (two words) instead. We use the term 2604``path'' only for search paths, which are lists of file names. 2605 2606Please do not use the term ``illegal'' to refer to erroneous input to a 2607computer program. Please use ``invalid'' for this, and reserve the term 2608``illegal'' for violations of law. 2609 2610@node Manual Structure Details 2611@section Manual Structure Details 2612 2613The title page of the manual should state the version of the programs or 2614packages documented in the manual. The Top node of the manual should 2615also contain this information. If the manual is changing more 2616frequently than or independent of the program, also state a version 2617number for the manual in both of these places. 2618 2619Each program documented in the manual should should have a node named 2620@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This 2621node (together with its subnodes, if any) should describe the program's 2622command line arguments and how to run it (the sort of information people 2623would look in a man page for). Start with an @samp{@@example} 2624containing a template for all the options and arguments that the program 2625uses. 2626 2627Alternatively, put a menu item in some menu whose item name fits one of 2628the above patterns. This identifies the node which that item points to 2629as the node for this purpose, regardless of the node's actual name. 2630 2631There will be automatic features for specifying a program name and 2632quickly reading just this part of its manual. 2633 2634If one manual describes several programs, it should have such a node for 2635each program described. 2636 2637@node NEWS File 2638@section The NEWS File 2639 2640In addition to its manual, the package should have a file named 2641@file{NEWS} which contains a list of user-visible changes worth 2642mentioning. In each new release, add items to the front of the file and 2643identify the version they pertain to. Don't discard old items; leave 2644them in the file after the newer items. This way, a user upgrading from 2645any previous version can see what is new. 2646 2647If the @file{NEWS} file gets very long, move some of the older items 2648into a file named @file{ONEWS} and put a note at the end referring the 2649user to that file. 2650 2651@node Change Logs 2652@section Change Logs 2653 2654Keep a change log to describe all the changes made to program source 2655files. The purpose of this is so that people investigating bugs in the 2656future will know about the changes that might have introduced the bug. 2657Often a new bug can be found by looking at what was recently changed. 2658More importantly, change logs can help you eliminate conceptual 2659inconsistencies between different parts of a program, by giving you a 2660history of how the conflicting concepts arose and who they came from. 2661 2662@menu 2663* Change Log Concepts:: 2664* Style of Change Logs:: 2665* Simple Changes:: 2666* Conditional Changes:: 2667@end menu 2668 2669@node Change Log Concepts 2670@subsection Change Log Concepts 2671 2672You can think of the change log as a conceptual ``undo list'' which 2673explains how earlier versions were different from the current version. 2674People can see the current version; they don't need the change log 2675to tell them what is in it. What they want from a change log is a 2676clear explanation of how the earlier version differed. 2677 2678The change log file is normally called @file{ChangeLog} and covers an 2679entire directory. Each directory can have its own change log, or a 2680directory can use the change log of its parent directory--it's up to 2681you. 2682 2683Another alternative is to record change log information with a version 2684control system such as RCS or CVS. This can be converted automatically 2685to a @file{ChangeLog} file. 2686 2687There's no need to describe the full purpose of the changes or how they 2688work together. If you think that a change calls for explanation, you're 2689probably right. Please do explain it---but please put the explanation 2690in comments in the code, where people will see it whenever they see the 2691code. For example, ``New function'' is enough for the change log when 2692you add a function, because there should be a comment before the 2693function definition to explain what it does. 2694 2695However, sometimes it is useful to write one line to describe the 2696overall purpose of a batch of changes. 2697 2698The easiest way to add an entry to @file{ChangeLog} is with the Emacs 2699command @kbd{M-x add-change-log-entry}. An entry should have an 2700asterisk, the name of the changed file, and then in parentheses the name 2701of the changed functions, variables or whatever, followed by a colon. 2702Then describe the changes you made to that function or variable. 2703 2704@node Style of Change Logs 2705@subsection Style of Change Logs 2706 2707Here are some examples of change log entries: 2708 2709@example 2710* register.el (insert-register): Return nil. 2711(jump-to-register): Likewise. 2712 2713* sort.el (sort-subr): Return nil. 2714 2715* tex-mode.el (tex-bibtex-file, tex-file, tex-region): 2716Restart the tex shell if process is gone or stopped. 2717(tex-shell-running): New function. 2718 2719* expr.c (store_one_arg): Round size up for move_block_to_reg. 2720(expand_call): Round up when emitting USE insns. 2721* stmt.c (assign_parms): Round size up for move_block_from_reg. 2722@end example 2723 2724It's important to name the changed function or variable in full. Don't 2725abbreviate function or variable names, and don't combine them. 2726Subsequent maintainers will often search for a function name to find all 2727the change log entries that pertain to it; if you abbreviate the name, 2728they won't find it when they search. 2729 2730For example, some people are tempted to abbreviate groups of function 2731names by writing @samp{* register.el (@{insert,jump-to@}-register)}; 2732this is not a good idea, since searching for @code{jump-to-register} or 2733@code{insert-register} would not find that entry. 2734 2735Separate unrelated change log entries with blank lines. When two 2736entries represent parts of the same change, so that they work together, 2737then don't put blank lines between them. Then you can omit the file 2738name and the asterisk when successive entries are in the same file. 2739 2740@node Simple Changes 2741@subsection Simple Changes 2742 2743Certain simple kinds of changes don't need much detail in the change 2744log. 2745 2746When you change the calling sequence of a function in a simple fashion, 2747and you change all the callers of the function, there is no need to make 2748individual entries for all the callers that you changed. Just write in 2749the entry for the function being called, ``All callers changed.'' 2750 2751@example 2752* keyboard.c (Fcommand_execute): New arg SPECIAL. 2753All callers changed. 2754@end example 2755 2756When you change just comments or doc strings, it is enough to write an 2757entry for the file, without mentioning the functions. Just ``Doc 2758fixes'' is enough for the change log. 2759 2760There's no need to make change log entries for documentation files. 2761This is because documentation is not susceptible to bugs that are hard 2762to fix. Documentation does not consist of parts that must interact in a 2763precisely engineered fashion. To correct an error, you need not know 2764the history of the erroneous passage; it is enough to compare what the 2765documentation says with the way the program actually works. 2766 2767@node Conditional Changes 2768@subsection Conditional Changes 2769 2770C programs often contain compile-time @code{#if} conditionals. Many 2771changes are conditional; sometimes you add a new definition which is 2772entirely contained in a conditional. It is very useful to indicate in 2773the change log the conditions for which the change applies. 2774 2775Our convention for indicating conditional changes is to use square 2776brackets around the name of the condition. 2777 2778Here is a simple example, describing a change which is conditional but 2779does not have a function or entity name associated with it: 2780 2781@example 2782* xterm.c [SOLARIS2]: Include string.h. 2783@end example 2784 2785Here is an entry describing a new definition which is entirely 2786conditional. This new definition for the macro @code{FRAME_WINDOW_P} is 2787used only when @code{HAVE_X_WINDOWS} is defined: 2788 2789@example 2790* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. 2791@end example 2792 2793Here is an entry for a change within the function @code{init_display}, 2794whose definition as a whole is unconditional, but the changes themselves 2795are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional: 2796 2797@example 2798* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. 2799@end example 2800 2801Here is an entry for a change that takes affect only when 2802a certain macro is @emph{not} defined: 2803 2804@example 2805(gethostname) [!HAVE_SOCKETS]: Replace with winsock version. 2806@end example 2807 2808@node Man Pages 2809@section Man Pages 2810 2811In the GNU project, man pages are secondary. It is not necessary or 2812expected for every GNU program to have a man page, but some of them do. 2813It's your choice whether to include a man page in your program. 2814 2815When you make this decision, consider that supporting a man page 2816requires continual effort each time the program is changed. The time 2817you spend on the man page is time taken away from more useful work. 2818 2819For a simple program which changes little, updating the man page may be 2820a small job. Then there is little reason not to include a man page, if 2821you have one. 2822 2823For a large program that changes a great deal, updating a man page may 2824be a substantial burden. If a user offers to donate a man page, you may 2825find this gift costly to accept. It may be better to refuse the man 2826page unless the same person agrees to take full responsibility for 2827maintaining it---so that you can wash your hands of it entirely. If 2828this volunteer later ceases to do the job, then don't feel obliged to 2829pick it up yourself; it may be better to withdraw the man page from the 2830distribution until someone else agrees to update it. 2831 2832When a program changes only a little, you may feel that the 2833discrepancies are small enough that the man page remains useful without 2834updating. If so, put a prominent note near the beginning of the man 2835page explaining that you don't maintain it and that the Texinfo manual 2836is more authoritative. The note should say how to access the Texinfo 2837documentation. 2838 2839@node Reading other Manuals 2840@section Reading other Manuals 2841 2842There may be non-free books or documentation files that describe the 2843program you are documenting. 2844 2845It is ok to use these documents for reference, just as the author of a 2846new algebra textbook can read other books on algebra. A large portion 2847of any non-fiction book consists of facts, in this case facts about how 2848a certain program works, and these facts are necessarily the same for 2849everyone who writes about the subject. But be careful not to copy your 2850outline structure, wording, tables or examples from preexisting non-free 2851documentation. Copying from free documentation may be ok; please check 2852with the FSF about the individual case. 2853 2854@node Managing Releases 2855@chapter The Release Process 2856 2857Making a release is more than just bundling up your source files in a 2858tar file and putting it up for FTP. You should set up your software so 2859that it can be configured to run on a variety of systems. Your Makefile 2860should conform to the GNU standards described below, and your directory 2861layout should also conform to the standards discussed below. Doing so 2862makes it easy to include your package into the larger framework of 2863all GNU software. 2864 2865@menu 2866* Configuration:: How Configuration Should Work 2867* Makefile Conventions:: Makefile Conventions 2868* Releases:: Making Releases 2869@end menu 2870 2871@node Configuration 2872@section How Configuration Should Work 2873 2874Each GNU distribution should come with a shell script named 2875@code{configure}. This script is given arguments which describe the 2876kind of machine and system you want to compile the program for. 2877 2878The @code{configure} script must record the configuration options so 2879that they affect compilation. 2880 2881One way to do this is to make a link from a standard name such as 2882@file{config.h} to the proper configuration file for the chosen system. 2883If you use this technique, the distribution should @emph{not} contain a 2884file named @file{config.h}. This is so that people won't be able to 2885build the program without configuring it first. 2886 2887Another thing that @code{configure} can do is to edit the Makefile. If 2888you do this, the distribution should @emph{not} contain a file named 2889@file{Makefile}. Instead, it should include a file @file{Makefile.in} which 2890contains the input used for editing. Once again, this is so that people 2891won't be able to build the program without configuring it first. 2892 2893If @code{configure} does write the @file{Makefile}, then @file{Makefile} 2894should have a target named @file{Makefile} which causes @code{configure} 2895to be rerun, setting up the same configuration that was set up last 2896time. The files that @code{configure} reads should be listed as 2897dependencies of @file{Makefile}. 2898 2899All the files which are output from the @code{configure} script should 2900have comments at the beginning explaining that they were generated 2901automatically using @code{configure}. This is so that users won't think 2902of trying to edit them by hand. 2903 2904The @code{configure} script should write a file named @file{config.status} 2905which describes which configuration options were specified when the 2906program was last configured. This file should be a shell script which, 2907if run, will recreate the same configuration. 2908 2909The @code{configure} script should accept an option of the form 2910@samp{--srcdir=@var{dirname}} to specify the directory where sources are found 2911(if it is not the current directory). This makes it possible to build 2912the program in a separate directory, so that the actual source directory 2913is not modified. 2914 2915If the user does not specify @samp{--srcdir}, then @code{configure} should 2916check both @file{.} and @file{..} to see if it can find the sources. If 2917it finds the sources in one of these places, it should use them from 2918there. Otherwise, it should report that it cannot find the sources, and 2919should exit with nonzero status. 2920 2921Usually the easy way to support @samp{--srcdir} is by editing a 2922definition of @code{VPATH} into the Makefile. Some rules may need to 2923refer explicitly to the specified source directory. To make this 2924possible, @code{configure} can add to the Makefile a variable named 2925@code{srcdir} whose value is precisely the specified directory. 2926 2927The @code{configure} script should also take an argument which specifies the 2928type of system to build the program for. This argument should look like 2929this: 2930 2931@example 2932@var{cpu}-@var{company}-@var{system} 2933@end example 2934 2935For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. 2936 2937The @code{configure} script needs to be able to decode all plausible 2938alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} 2939would be a valid alias. For many programs, @samp{vax-dec-ultrix} would 2940be an alias for @samp{vax-dec-bsd}, simply because the differences 2941between Ultrix and @sc{BSD} are rarely noticeable, but a few programs 2942might need to distinguish them. 2943@c Real 4.4BSD now runs on some Suns. 2944 2945There is a shell script called @file{config.sub} that you can use 2946as a subroutine to validate system types and canonicalize aliases. 2947 2948Other options are permitted to specify in more detail the software 2949or hardware present on the machine, and include or exclude optional 2950parts of the package: 2951 2952@table @samp 2953@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} 2954Configure the package to build and install an optional user-level 2955facility called @var{feature}. This allows users to choose which 2956optional features to include. Giving an optional @var{parameter} of 2957@samp{no} should omit @var{feature}, if it is built by default. 2958 2959No @samp{--enable} option should @strong{ever} cause one feature to 2960replace another. No @samp{--enable} option should ever substitute one 2961useful behavior for another useful behavior. The only proper use for 2962@samp{--enable} is for questions of whether to build part of the program 2963or exclude it. 2964 2965@item --with-@var{package} 2966@c @r{[}=@var{parameter}@r{]} 2967The package @var{package} will be installed, so configure this package 2968to work with @var{package}. 2969 2970@c Giving an optional @var{parameter} of 2971@c @samp{no} should omit @var{package}, if it is used by default. 2972 2973Possible values of @var{package} include 2974@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, 2975@samp{gdb}, 2976@samp{x}, 2977and 2978@samp{x-toolkit}. 2979 2980Do not use a @samp{--with} option to specify the file name to use to 2981find certain files. That is outside the scope of what @samp{--with} 2982options are for. 2983 2984@item --nfp 2985The target machine has no floating point processor. 2986 2987@item --gas 2988The target machine assembler is GAS, the GNU assembler. 2989This is obsolete; users should use @samp{--with-gnu-as} instead. 2990 2991@item --x 2992The target machine has the X Window System installed. 2993This is obsolete; users should use @samp{--with-x} instead. 2994@end table 2995 2996All @code{configure} scripts should accept all of these ``detail'' 2997options, whether or not they make any difference to the particular 2998package at hand. In particular, they should accept any option that 2999starts with @samp{--with-} or @samp{--enable-}. This is so users will 3000be able to configure an entire GNU source tree at once with a single set 3001of options. 3002 3003You will note that the categories @samp{--with-} and @samp{--enable-} 3004are narrow: they @strong{do not} provide a place for any sort of option 3005you might think of. That is deliberate. We want to limit the possible 3006configuration options in GNU software. We do not want GNU programs to 3007have idiosyncratic configuration options. 3008 3009Packages that perform part of the compilation process may support cross-compilation. 3010In such a case, the host and target machines for the program may be 3011different. The @code{configure} script should normally treat the 3012specified type of system as both the host and the target, thus producing 3013a program which works for the same type of machine that it runs on. 3014 3015The way to build a cross-compiler, cross-assembler, or what have you, is 3016to specify the option @samp{--host=@var{hosttype}} when running 3017@code{configure}. This specifies the host system without changing the 3018type of target system. The syntax for @var{hosttype} is the same as 3019described above. 3020 3021Bootstrapping a cross-compiler requires compiling it on a machine other 3022than the host it will run on. Compilation packages accept a 3023configuration option @samp{--build=@var{hosttype}} for specifying the 3024configuration on which you will compile them, in case that is different 3025from the host. 3026 3027Programs for which cross-operation is not meaningful need not accept the 3028@samp{--host} option, because configuring an entire operating system for 3029cross-operation is not a meaningful thing. 3030 3031Some programs have ways of configuring themselves automatically. If 3032your program is set up to do this, your @code{configure} script can simply 3033ignore most of its arguments. 3034 3035@comment The makefile standards are in a separate file that is also 3036@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. 3037@comment For this document, turn chapters into sections, etc. 3038@lowersections 3039@include make-stds.texi 3040@raisesections 3041 3042@node Releases 3043@section Making Releases 3044 3045Package the distribution of @code{Foo version 69.96} up in a gzipped tar 3046file with the name @file{foo-69.96.tar.gz}. It should unpack into a 3047subdirectory named @file{foo-69.96}. 3048 3049Building and installing the program should never modify any of the files 3050contained in the distribution. This means that all the files that form 3051part of the program in any way must be classified into @dfn{source 3052files} and @dfn{non-source files}. Source files are written by humans 3053and never changed automatically; non-source files are produced from 3054source files by programs under the control of the Makefile. 3055 3056Naturally, all the source files must be in the distribution. It is okay 3057to include non-source files in the distribution, provided they are 3058up-to-date and machine-independent, so that building the distribution 3059normally will never modify them. We commonly include non-source files 3060produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid 3061unnecessary dependencies between our distributions, so that users can 3062install whichever packages they want to install. 3063 3064Non-source files that might actually be modified by building and 3065installing the program should @strong{never} be included in the 3066distribution. So if you do distribute non-source files, always make 3067sure they are up to date when you make a new distribution. 3068 3069Make sure that the directory into which the distribution unpacks (as 3070well as any subdirectories) are all world-writable (octal mode 777). 3071This is so that old versions of @code{tar} which preserve the 3072ownership and permissions of the files from the tar archive will be 3073able to extract all the files even if the user is unprivileged. 3074 3075Make sure that all the files in the distribution are world-readable. 3076 3077Make sure that no file name in the distribution is more than 14 3078characters long. Likewise, no file created by building the program 3079should have a name longer than 14 characters. The reason for this is 3080that some systems adhere to a foolish interpretation of the @sc{posix} 3081standard, and refuse to open a longer name, rather than truncating as 3082they did in the past. 3083 3084Don't include any symbolic links in the distribution itself. If the tar 3085file contains symbolic links, then people cannot even unpack it on 3086systems that don't support symbolic links. Also, don't use multiple 3087names for one file in different directories, because certain file 3088systems cannot handle this and that prevents unpacking the 3089distribution. 3090 3091Try to make sure that all the file names will be unique on MS-DOS. A 3092name on MS-DOS consists of up to 8 characters, optionally followed by a 3093period and up to three characters. MS-DOS will truncate extra 3094characters both before and after the period. Thus, 3095@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they 3096are truncated to @file{foobarha.c} and @file{foobarha.o}, which are 3097distinct. 3098 3099Include in your distribution a copy of the @file{texinfo.tex} you used 3100to test print any @file{*.texinfo} or @file{*.texi} files. 3101 3102Likewise, if your program uses small GNU software packages like regex, 3103getopt, obstack, or termcap, include them in the distribution file. 3104Leaving them out would make the distribution file a little smaller at 3105the expense of possible inconvenience to a user who doesn't know what 3106other files to get. 3107 3108@contents 3109 3110@bye 3111Local variables: 3112update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate " 3113update-date-trailing-regexp: "" 3114eval: (load "/gd/gnuorg/update-date.el") 3115eval: (add-hook 'write-file-hooks 'update-date) 3116End: 3117