1 \input texinfo @c -*-texinfo-*-
3 @setfilename standards.info
4 @settitle GNU Coding Standards
5 @c This date is automagically updated when you save this file:
6 @set lastupdate January 22, 2007
9 @dircategory GNU organization
11 * Standards: (standards). GNU coding standards.
14 @c @setchapternewpage odd
15 @setchapternewpage off
17 @c Put everything in one index (arbitrarily chosen to be the concept index).
23 @c This is used by a cross ref in make-stds.texi
33 The GNU coding standards, last updated @value{lastupdate}.
35 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
36 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
39 Permission is granted to copy, distribute and/or modify this document
40 under the terms of the GNU Free Documentation License, Version 1.2
41 or any later version published by the Free Software Foundation;
42 with no Invariant Sections, with no
43 Front-Cover Texts, and with no Back-Cover Texts.
44 A copy of the license is included in the section entitled ``GNU
45 Free Documentation License''.
49 @title GNU Coding Standards
50 @author Richard Stallman, et al.
51 @author last updated @value{lastupdate}
53 @vskip 0pt plus 1filll
60 @node Top, Preface, (dir), (dir)
67 * Preface:: About the GNU Coding Standards
68 * Legal Issues:: Keeping Free Software Free
69 * Design Advice:: General Program Design
70 * Program Behavior:: Program Behavior for All Programs
71 * Writing C:: Making The Best Use of C
72 * Documentation:: Documenting Programs
73 * Managing Releases:: The Release Process
74 * References:: References to Non-Free Software or Documentation
75 * Copying This Manual:: How to Make Copies of This Manual
81 @chapter About the GNU Coding Standards
83 The GNU Coding Standards were written by Richard Stallman and other GNU
84 Project volunteers. Their purpose is to make the GNU system clean,
85 consistent, and easy to install. This document can also be read as a
86 guide to writing portable, robust and reliable programs. It focuses on
87 programs written in C, but many of the rules and principles are useful
88 even if you write in another programming language. The rules often
89 state reasons for writing in a certain way.
91 This release of the GNU Coding Standards was last updated
94 @cindex where to obtain @code{standards.texi}
95 @cindex downloading this manual
96 If you did not obtain this file directly from the GNU project and
97 recently, please check for a newer version. You can get the GNU
98 Coding Standards from the GNU web server in many
99 different formats, including the Texinfo source, PDF, HTML, DVI, plain
100 text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
102 Corrections or suggestions for this document should be sent to
103 @email{bug-standards@@gnu.org}. If you make a suggestion, please include a
104 suggested new wording for it; our time is limited. We prefer a context
105 diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
106 you don't have those files, please mail your suggestion anyway.
108 These standards cover the minimum of what is important when writing a
109 GNU package. Likely, the needs for additional standards will come up.
110 Sometimes, you might suggest that such standards be added to this
111 document. If you think your standards would be generally useful, please
114 You should also set standards for your package on many questions not
115 addressed or not firmly specified here. The most important point is to
116 be self-consistent---try to stick to the conventions you pick, and try
117 to document them as much as possible. That way, your program will be
118 more maintainable by others.
120 The GNU Hello program serves as an example of how to follow the GNU
121 coding standards for a trivial program.
122 @uref{http://www.gnu.org/software/hello/hello.html}.
125 @chapter Keeping Free Software Free
126 @cindex legal aspects
128 This chapter discusses how you can make sure that GNU software
129 avoids legal difficulties, and other related issues.
132 * Reading Non-Free Code:: Referring to Proprietary Programs
133 * Contributions:: Accepting Contributions
134 * Trademarks:: How We Deal with Trademark Issues
137 @node Reading Non-Free Code
138 @section Referring to Proprietary Programs
139 @cindex proprietary programs
140 @cindex avoiding proprietary code
142 Don't in any circumstances refer to Unix source code for or during
143 your work on GNU! (Or to any other proprietary programs.)
145 If you have a vague recollection of the internals of a Unix program,
146 this does not absolutely mean you can't write an imitation of it, but
147 do try to organize the imitation internally along different lines,
148 because this is likely to make the details of the Unix version
149 irrelevant and dissimilar to your results.
151 For example, Unix utilities were generally optimized to minimize
152 memory use; if you go for speed instead, your program will be very
153 different. You could keep the entire input file in memory and scan it
154 there instead of using stdio. Use a smarter algorithm discovered more
155 recently than the Unix program. Eliminate use of temporary files. Do
156 it in one pass instead of two (we did this in the assembler).
158 Or, on the contrary, emphasize simplicity instead of speed. For some
159 applications, the speed of today's computers makes simpler algorithms
162 Or go for generality. For example, Unix programs often have static
163 tables or fixed-size strings, which make for arbitrary limits; use
164 dynamic allocation instead. Make sure your program handles NULs and
165 other funny characters in the input files. Add a programming language
166 for extensibility and write part of the program in that language.
168 Or turn some parts of the program into independently usable libraries.
169 Or use a simple garbage collector instead of tracking precisely when
170 to free memory, or use a new GNU facility such as obstacks.
173 @section Accepting Contributions
175 @cindex accepting contributions
177 If the program you are working on is copyrighted by the Free Software
178 Foundation, then when someone else sends you a piece of code to add to
179 the program, we need legal papers to use it---just as we asked you to
180 sign papers initially. @emph{Each} person who makes a nontrivial
181 contribution to a program must sign some sort of legal papers in order
182 for us to have clear title to the program; the main author alone is not
185 So, before adding in any contributions from other people, please tell
186 us, so we can arrange to get the papers. Then wait until we tell you
187 that we have received the signed papers, before you actually use the
190 This applies both before you release the program and afterward. If
191 you receive diffs to fix a bug, and they make significant changes, we
192 need legal papers for that change.
194 This also applies to comments and documentation files. For copyright
195 law, comments and code are just text. Copyright applies to all kinds of
196 text, so we need legal papers for all kinds.
198 We know it is frustrating to ask for legal papers; it's frustrating for
199 us as well. But if you don't wait, you are going out on a limb---for
200 example, what if the contributor's employer won't sign a disclaimer?
201 You might have to take that code out again!
203 You don't need papers for changes of a few lines here or there, since
204 they are not significant for copyright purposes. Also, you don't need
205 papers if all you get from the suggestion is some ideas, not actual code
206 which you use. For example, if someone sent you one implementation, but
207 you write a different implementation of the same idea, you don't need to
210 The very worst thing is if you forget to tell us about the other
211 contributor. We could be very embarrassed in court some day as a
214 We have more detailed advice for maintainers of programs; if you have
215 reached the stage of actually maintaining a program for GNU (whether
216 released or not), please ask us for a copy. It is also available
217 online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.
223 Please do not include any trademark acknowledgements in GNU software
224 packages or documentation.
226 Trademark acknowledgements are the statements that such-and-such is a
227 trademark of so-and-so. The GNU Project has no objection to the basic
228 idea of trademarks, but these acknowledgements feel like kowtowing,
229 and there is no legal requirement for them, so we don't use them.
231 What is legally required, as regards other people's trademarks, is to
232 avoid using them in ways which a reader might reasonably understand as
233 naming or labeling our own programs or activities. For example, since
234 ``Objective C'' is (or at least was) a trademark, we made sure to say
235 that we provide a ``compiler for the Objective C language'' rather
236 than an ``Objective C compiler''. The latter would have been meant as
237 a shorter way of saying the former, but it does not explicitly state
238 the relationship, so it could be misinterpreted as using ``Objective
239 C'' as a label for the compiler rather than for the language.
241 Please don't use ``win'' as an abbreviation for Microsoft Windows in
242 GNU software or documentation. In hacker terminology, calling
243 something a ``win'' is a form of praise. If you wish to praise
244 Microsoft Windows when speaking on your own, by all means do so, but
245 not in GNU software. Usually we write the name ``Windows'' in full,
246 but when brevity is very important (as in file names and sometimes
247 symbol names), we abbreviate it to ``w''. For instance, the files and
248 functions in Emacs that deal with Windows start with @samp{w32}.
251 @chapter General Program Design
252 @cindex program design
254 This chapter discusses some of the issues you should take into
255 account when designing your program.
257 @c Standard or ANSI C
259 @c In 1989 the American National Standards Institute (ANSI) standardized
260 @c C as standard X3.159-1989. In December of that year the
261 @c International Standards Organization ISO adopted the ANSI C standard
262 @c making minor changes. In 1990 ANSI then re-adopted ISO standard
263 @c C. This version of C is known as either ANSI C or Standard C.
265 @c A major revision of the C Standard appeared in 1999.
268 * Source Language:: Which languages to use.
269 * Compatibility:: Compatibility with other implementations
270 * Using Extensions:: Using non-standard features
271 * Standard C:: Using Standard C features
272 * Conditional Compilation:: Compiling Code Only If A Conditional is True
275 @node Source Language
276 @section Which Languages to Use
277 @cindex programming languages
279 When you want to use a language that gets compiled and runs at high
280 speed, the best language to use is C. Using another language is like
281 using a non-standard feature: it will cause trouble for users. Even if
282 GCC supports the other language, users may find it inconvenient to have
283 to install the compiler for that other language in order to build your
284 program. For example, if you write your program in C++, people will
285 have to install the GNU C++ compiler in order to compile your program.
287 C has one other advantage over C++ and other compiled languages: more
288 people know C, so more people will find it easy to read and modify the
289 program if it is written in C.
291 So in general it is much better to use C, rather than the
292 comparable alternatives.
294 But there are two exceptions to that conclusion:
298 It is no problem to use another language to write a tool specifically
299 intended for use with that language. That is because the only people
300 who want to build the tool will be those who have installed the other
304 If an application is of interest only to a narrow part of the community,
305 then the question of which language it is written in has less effect on
306 other people, so you may as well please yourself.
309 Many programs are designed to be extensible: they include an interpreter
310 for a language that is higher level than C. Often much of the program
311 is written in that language, too. The Emacs editor pioneered this
315 The standard extensibility interpreter for GNU software is GUILE
316 (@uref{http://www.gnu.org/software/guile/}), which implements the
317 language Scheme (an especially clean and simple dialect of Lisp). We
318 don't reject programs written in other ``scripting languages'' such as
319 Perl and Python, but using GUILE is very important for the overall
320 consistency of the GNU system.
323 @section Compatibility with Other Implementations
324 @cindex compatibility with C and @sc{posix} standards
325 @cindex @sc{posix} compatibility
327 With occasional exceptions, utility programs and libraries for GNU
328 should be upward compatible with those in Berkeley Unix, and upward
329 compatible with Standard C if Standard C specifies their
330 behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
333 When these standards conflict, it is useful to offer compatibility
334 modes for each of them.
336 @cindex options for compatibility
337 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
338 free to make the extensions anyway, and include a @samp{--ansi},
339 @samp{--posix}, or @samp{--compatible} option to turn them off.
340 However, if the extension has a significant chance of breaking any real
341 programs or scripts, then it is not really upward compatible. So you
342 should try to redesign its interface to make it upward compatible.
344 @cindex @code{POSIXLY_CORRECT}, environment variable
345 Many GNU programs suppress extensions that conflict with @sc{posix} if the
346 environment variable @code{POSIXLY_CORRECT} is defined (even if it is
347 defined with a null value). Please make your program recognize this
348 variable if appropriate.
350 When a feature is used only by users (not by programs or command
351 files), and it is done poorly in Unix, feel free to replace it
352 completely with something totally different and better. (For example,
353 @code{vi} is replaced with Emacs.) But it is nice to offer a compatible
354 feature as well. (There is a free @code{vi} clone, so we offer it.)
356 Additional useful features are welcome regardless of whether
357 there is any precedent for them.
359 @node Using Extensions
360 @section Using Non-standard Features
361 @cindex non-standard extensions
363 Many GNU facilities that already exist support a number of convenient
364 extensions over the comparable Unix facilities. Whether to use these
365 extensions in implementing your program is a difficult question.
367 On the one hand, using the extensions can make a cleaner program.
368 On the other hand, people will not be able to build the program
369 unless the other GNU tools are available. This might cause the
370 program to work on fewer kinds of machines.
372 With some extensions, it might be easy to provide both alternatives.
373 For example, you can define functions with a ``keyword'' @code{INLINE}
374 and define that as a macro to expand into either @code{inline} or
375 nothing, depending on the compiler.
377 In general, perhaps it is best not to use the extensions if you can
378 straightforwardly do without them, but to use the extensions if they
379 are a big improvement.
381 An exception to this rule are the large, established programs (such as
382 Emacs) which run on a great variety of systems. Using GNU extensions in
383 such programs would make many users unhappy, so we don't do that.
385 Another exception is for programs that are used as part of compilation:
386 anything that must be compiled with other compilers in order to
387 bootstrap the GNU compilation facilities. If these require the GNU
388 compiler, then no one can compile them without having them installed
389 already. That would be extremely troublesome in certain cases.
392 @section Standard C and Pre-Standard C
393 @cindex @sc{ansi} C standard
395 1989 Standard C is widespread enough now that it is ok to use its
396 features in new programs. There is one exception: do not ever use the
397 ``trigraph'' feature of Standard C.
399 1999 Standard C is not widespread yet, so please do not require its
400 features in programs. It is ok to use its features if they are present.
402 However, it is easy to support pre-standard compilers in most programs,
403 so if you know how to do that, feel free. If a program you are
404 maintaining has such support, you should try to keep it working.
406 @cindex function prototypes
407 To support pre-standard C, instead of writing function definitions in
408 standard prototype form,
417 write the definition in pre-standard style like this,
427 and use a separate declaration to specify the argument prototype:
433 You need such a declaration anyway, in a header file, to get the benefit
434 of prototypes in all the files where the function is called. And once
435 you have the declaration, you normally lose nothing by writing the
436 function definition in the pre-standard style.
438 This technique does not work for integer types narrower than @code{int}.
439 If you think of an argument as being of a type narrower than @code{int},
440 declare it as @code{int} instead.
442 There are a few special cases where this technique is hard to use. For
443 example, if a function argument needs to hold the system type
444 @code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
445 @code{int} on some machines; but you cannot use @code{int} instead,
446 because @code{dev_t} is wider than @code{int} on some machines. There
447 is no type you can safely use on all machines in a non-standard
448 definition. The only way to support non-standard C and pass such an
449 argument is to check the width of @code{dev_t} using Autoconf and choose
450 the argument type accordingly. This may not be worth the trouble.
452 In order to support pre-standard compilers that do not recognize
453 prototypes, you may want to use a preprocessor macro like this:
456 /* Declare the prototype for a general external function. */
457 #if defined (__STDC__) || defined (WINDOWSNT)
458 #define P_(proto) proto
464 @node Conditional Compilation
465 @section Conditional Compilation
467 When supporting configuration options already known when building your
468 program we prefer using @code{if (... )} over conditional compilation,
469 as in the former case the compiler is able to perform more extensive
470 checking of all possible code paths.
472 For example, please write
492 A modern compiler such as GCC will generate exactly the same code in
493 both cases, and we have been using similar techniques with good success
494 in several projects. Of course, the former method assumes that
495 @code{HAS_FOO} is defined as either 0 or 1.
497 While this is not a silver bullet solving all portability problems,
498 and is not always appropriate, following this policy would have saved
499 GCC developers many hours, or even days, per year.
501 In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
502 GCC which cannot be simply used in @code{if( ...)} statements, there is
503 an easy workaround. Simply introduce another macro
504 @code{HAS_REVERSIBLE_CC_MODE} as in the following example:
507 #ifdef REVERSIBLE_CC_MODE
508 #define HAS_REVERSIBLE_CC_MODE 1
510 #define HAS_REVERSIBLE_CC_MODE 0
514 @node Program Behavior
515 @chapter Program Behavior for All Programs
517 This chapter describes conventions for writing robust
518 software. It also describes general standards for error messages, the
519 command line interface, and how libraries should behave.
522 * Non-GNU Standards:: We consider standards such as POSIX;
523 we don't "obey" them.
524 * Semantics:: Writing robust programs
525 * Libraries:: Library behavior
526 * Errors:: Formatting error messages
527 * User Interfaces:: Standards about interfaces generally
528 * Graphical Interfaces:: Standards for graphical interfaces
529 * Command-Line Interfaces:: Standards for command line interfaces
530 * Option Table:: Table of long options
531 * Memory Usage:: When and how to care about memory needs
532 * File Usage:: Which files to use, and where
535 @node Non-GNU Standards
536 @section Non-GNU Standards
538 The GNU Project regards standards published by other organizations as
539 suggestions, not orders. We consider those standards, but we do not
540 ``obey'' them. In developing a GNU program, you should implement
541 an outside standard's specifications when that makes the GNU system
542 better overall in an objective sense. When it doesn't, you shouldn't.
544 In most cases, following published standards is convenient for
545 users---it means that their programs or scripts will work more
546 portably. For instance, GCC implements nearly all the features of
547 Standard C as specified by that standard. C program developers would
548 be unhappy if it did not. And GNU utilities mostly follow
549 specifications of POSIX.2; shell script writers and users would be
550 unhappy if our programs were incompatible.
552 But we do not follow either of these specifications rigidly, and there
553 are specific points on which we decided not to follow them, so as to
554 make the GNU system better for users.
556 For instance, Standard C says that nearly all extensions to C are
557 prohibited. How silly! GCC implements many extensions, some of which
558 were later adopted as part of the standard. If you want these
559 constructs to give an error message as ``required'' by the standard,
560 you must specify @samp{--pedantic}, which was implemented only so that
561 we can say ``GCC is a 100% implementation of the standard,'' not
562 because there is any reason to actually use it.
564 POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
565 default in units of 512 bytes. What users want is units of 1k, so
566 that is what we do by default. If you want the ridiculous behavior
567 ``required'' by POSIX, you must set the environment variable
568 @samp{POSIXLY_CORRECT} (which was originally going to be named
569 @samp{POSIX_ME_HARDER}).
571 GNU utilities also depart from the letter of the POSIX.2 specification
572 when they support long-named command-line options, and intermixing
573 options with ordinary arguments. This minor incompatibility with
574 POSIX is never a problem in practice, and it is very useful.
576 In particular, don't reject a new feature, or remove an old one,
577 merely because a standard says it is ``forbidden'' or ``deprecated.''
580 @section Writing Robust Programs
582 @cindex arbitrary limits on data
583 Avoid arbitrary limits on the length or number of @emph{any} data
584 structure, including file names, lines, files, and symbols, by allocating
585 all data structures dynamically. In most Unix utilities, ``long lines
586 are silently truncated''. This is not acceptable in a GNU utility.
588 @cindex @code{NUL} characters
589 Utilities reading files should not drop NUL characters, or any other
590 nonprinting characters @emph{including those with codes above 0177}.
591 The only sensible exceptions would be utilities specifically intended
592 for interface to certain types of terminals or printers
593 that can't handle those characters.
594 Whenever possible, try to make programs work properly with
595 sequences of bytes that represent multibyte characters, using encodings
596 such as UTF-8 and others.
598 @cindex error messages
599 Check every system call for an error return, unless you know you wish to
600 ignore errors. Include the system error text (from @code{perror} or
601 equivalent) in @emph{every} error message resulting from a failing
602 system call, as well as the name of the file if any and the name of the
603 utility. Just ``cannot open foo.c'' or ``stat failed'' is not
606 @cindex @code{malloc} return value
607 @cindex memory allocation failure
608 Check every call to @code{malloc} or @code{realloc} to see if it
609 returned zero. Check @code{realloc} even if you are making the block
610 smaller; in a system that rounds block sizes to a power of 2,
611 @code{realloc} may get a different block if you ask for less space.
613 In Unix, @code{realloc} can destroy the storage block if it returns
614 zero. GNU @code{realloc} does not have this bug: if it fails, the
615 original block is unchanged. Feel free to assume the bug is fixed. If
616 you wish to run your program on Unix, and wish to avoid lossage in this
617 case, you can use the GNU @code{malloc}.
619 You must expect @code{free} to alter the contents of the block that was
620 freed. Anything you want to fetch from the block, you must fetch before
623 If @code{malloc} fails in a noninteractive program, make that a fatal
624 error. In an interactive program (one that reads commands from the
625 user), it is better to abort the command and return to the command
626 reader loop. This allows the user to kill other processes to free up
627 virtual memory, and then try the command again.
629 @cindex command-line arguments, decoding
630 Use @code{getopt_long} to decode arguments, unless the argument syntax
631 makes this unreasonable.
633 When static storage is to be written in during program execution, use
634 explicit C code to initialize it. Reserve C initialized declarations
635 for data that will not be changed.
638 Try to avoid low-level interfaces to obscure Unix data structures (such
639 as file directories, utmp, or the layout of kernel memory), since these
640 are less likely to work compatibly. If you need to find all the files
641 in a directory, use @code{readdir} or some other high-level interface.
642 These are supported compatibly by GNU.
644 @cindex signal handling
645 The preferred signal handling facilities are the BSD variant of
646 @code{signal}, and the @sc{posix} @code{sigaction} function; the
647 alternative USG @code{signal} interface is an inferior design.
649 Nowadays, using the @sc{posix} signal functions may be the easiest way
650 to make a program portable. If you use @code{signal}, then on GNU/Linux
651 systems running GNU libc version 1, you should include
652 @file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
653 behavior. It is up to you whether to support systems where
654 @code{signal} has only the USG behavior, or give up on them.
656 @cindex impossible conditions
657 In error checks that detect ``impossible'' conditions, just abort.
658 There is usually no point in printing any message. These checks
659 indicate the existence of bugs. Whoever wants to fix the bugs will have
660 to read the source code and run a debugger. So explain the problem with
661 comments in the source. The relevant data will be in variables, which
662 are easy to examine with the debugger, so there is no point moving them
665 Do not use a count of errors as the exit status for a program.
666 @emph{That does not work}, because exit status values are limited to 8
667 bits (0 through 255). A single run of the program might have 256
668 errors; if you try to return 256 as the exit status, the parent process
669 will see 0 as the status, and it will appear that the program succeeded.
671 @cindex temporary files
672 @cindex @code{TMPDIR} environment variable
673 If you make temporary files, check the @code{TMPDIR} environment
674 variable; if that variable is defined, use the specified directory
675 instead of @file{/tmp}.
677 In addition, be aware that there is a possible security problem when
678 creating temporary files in world-writable directories. In C, you can
679 avoid this problem by creating temporary files in this manner:
682 fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
686 or by using the @code{mkstemps} function from libiberty.
688 In bash, use @code{set -C} to avoid this problem.
691 @section Library Behavior
694 Try to make library functions reentrant. If they need to do dynamic
695 storage allocation, at least try to avoid any nonreentrancy aside from
696 that of @code{malloc} itself.
698 Here are certain name conventions for libraries, to avoid name
701 Choose a name prefix for the library, more than two characters long.
702 All external function and variable names should start with this
703 prefix. In addition, there should only be one of these in any given
704 library member. This usually means putting each one in a separate
707 An exception can be made when two external symbols are always used
708 together, so that no reasonable program could use one without the
709 other; then they can both go in the same file.
711 External symbols that are not documented entry points for the user
712 should have names beginning with @samp{_}. The @samp{_} should be
713 followed by the chosen name prefix for the library, to prevent
714 collisions with other libraries. These can go in the same files with
715 user entry points if you like.
717 Static functions and variables can be used as you like and need not
718 fit any naming convention.
721 @section Formatting Error Messages
722 @cindex formatting error messages
723 @cindex error messages, formatting
725 Error messages from compilers should look like this:
728 @var{source-file-name}:@var{lineno}: @var{message}
732 If you want to mention the column number, use one of these formats:
735 @var{source-file-name}:@var{lineno}:@var{column}: @var{message}
736 @var{source-file-name}:@var{lineno}.@var{column}: @var{message}
741 Line numbers should start from 1 at the beginning of the file, and
742 column numbers should start from 1 at the beginning of the line. (Both
743 of these conventions are chosen for compatibility.) Calculate column
744 numbers assuming that space and all ASCII printing characters have
745 equal width, and assuming tab stops every 8 columns.
747 The error message can also give both the starting and ending positions
748 of the erroneous text. There are several formats so that you can
749 avoid redundant information such as a duplicate line number.
750 Here are the possible formats:
753 @var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
754 @var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
755 @var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
759 When an error is spread over several files, you can use this format:
762 @var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
765 Error messages from other noninteractive programs should look like this:
768 @var{program}:@var{source-file-name}:@var{lineno}: @var{message}
772 when there is an appropriate source file, or like this:
775 @var{program}: @var{message}
779 when there is no relevant source file.
781 If you want to mention the column number, use this format:
784 @var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
787 In an interactive program (one that is reading commands from a
788 terminal), it is better not to include the program name in an error
789 message. The place to indicate which program is running is in the
790 prompt or with the screen layout. (When the same program runs with
791 input from a source other than a terminal, it is not interactive and
792 would do best to print error messages using the noninteractive style.)
794 The string @var{message} should not begin with a capital letter when
795 it follows a program name and/or file name, because that isn't the
796 beginning of a sentence. (The sentence conceptually starts at the
797 beginning of the line.) Also, it should not end with a period.
799 Error messages from interactive programs, and other messages such as
800 usage messages, should start with a capital letter. But they should not
803 @node User Interfaces
804 @section Standards for Interfaces Generally
806 @cindex program name and its behavior
807 @cindex behavior, dependent on program's name
808 Please don't make the behavior of a utility depend on the name used
809 to invoke it. It is useful sometimes to make a link to a utility
810 with a different name, and that should not change what it does.
812 Instead, use a run time option or a compilation switch or both
813 to select among the alternate behaviors.
815 @cindex output device and program's behavior
816 Likewise, please don't make the behavior of the program depend on the
817 type of output device it is used with. Device independence is an
818 important principle of the system's design; do not compromise it merely
819 to save someone from typing an option now and then. (Variation in error
820 message syntax when using a terminal is ok, because that is a side issue
821 that people do not depend on.)
823 If you think one behavior is most useful when the output is to a
824 terminal, and another is most useful when the output is a file or a
825 pipe, then it is usually best to make the default behavior the one that
826 is useful with output to a terminal, and have an option for the other
829 Compatibility requires certain programs to depend on the type of output
830 device. It would be disastrous if @code{ls} or @code{sh} did not do so
831 in the way all users expect. In some of these cases, we supplement the
832 program with a preferred alternate version that does not depend on the
833 output device type. For example, we provide a @code{dir} program much
834 like @code{ls} except that its default output format is always
837 @node Graphical Interfaces
838 @section Standards for Graphical Interfaces
839 @cindex graphical user interface
842 When you write a program that provides a graphical user interface,
843 please make it work with X Windows and the GTK+ toolkit unless the
844 functionality specifically requires some alternative (for example,
845 ``displaying jpeg images while in console mode'').
847 In addition, please provide a command-line interface to control the
848 functionality. (In many cases, the graphical user interface can be a
849 separate program which invokes the command-line program.) This is
850 so that the same jobs can be done from scripts.
854 Please also consider providing a CORBA interface (for use from GNOME), a
855 library interface (for use from C), and perhaps a keyboard-driven
856 console interface (for use by users from console mode). Once you are
857 doing the work to provide the functionality and the graphical interface,
858 these won't be much extra work.
860 @node Command-Line Interfaces
861 @section Standards for Command Line Interfaces
862 @cindex command-line interface
865 It is a good idea to follow the @sc{posix} guidelines for the
866 command-line options of a program. The easiest way to do this is to use
867 @code{getopt} to parse them. Note that the GNU version of @code{getopt}
868 will normally permit options anywhere among the arguments unless the
869 special argument @samp{--} is used. This is not what @sc{posix}
870 specifies; it is a GNU extension.
872 @cindex long-named options
873 Please define long-named options that are equivalent to the
874 single-letter Unix-style options. We hope to make GNU more user
875 friendly this way. This is easy to do with the GNU function
878 One of the advantages of long-named options is that they can be
879 consistent from program to program. For example, users should be able
880 to expect the ``verbose'' option of any GNU program which has one, to be
881 spelled precisely @samp{--verbose}. To achieve this uniformity, look at
882 the table of common long-option names when you choose the option names
883 for your program (@pxref{Option Table}).
885 It is usually a good idea for file names given as ordinary arguments to
886 be input files only; any output files would be specified using options
887 (preferably @samp{-o} or @samp{--output}). Even if you allow an output
888 file name as an ordinary argument for compatibility, try to provide an
889 option as another way to specify it. This will lead to more consistency
890 among GNU utilities, and fewer idiosyncrasies for users to remember.
892 @cindex standard command-line options
893 @cindex options, standard command-line
894 @cindex CGI programs, standard options for
895 @cindex PATH_INFO, specifying standard options as
896 All programs should support two standard options: @samp{--version}
897 and @samp{--help}. CGI programs should accept these as command-line
898 options, and also if given as the @env{PATH_INFO}; for instance,
899 visiting @url{http://example.org/p.cgi/--help} in a browser should
900 output the same information as invoking @samp{p.cgi --help} from the
904 @cindex @samp{--version} option
906 This option should direct the program to print information about its name,
907 version, origin and legal status, all on standard output, and then exit
908 successfully. Other options and arguments should be ignored once this
909 is seen, and the program should not perform its normal function.
911 @cindex canonical name of a program
912 @cindex program's canonical name
913 The first line is meant to be easy for a program to parse; the version
914 number proper starts after the last space. In addition, it contains
915 the canonical name for this program, in this format:
922 The program's name should be a constant string; @emph{don't} compute it
923 from @code{argv[0]}. The idea is to state the standard or canonical
924 name for the program, not its file name. There are other ways to find
925 out the precise file name where a command is found in @code{PATH}.
927 If the program is a subsidiary part of a larger package, mention the
928 package name in parentheses, like this:
931 emacsserver (GNU Emacs) 19.30
935 If the package has a version number which is different from this
936 program's version number, you can mention the package version number
937 just before the close-parenthesis.
939 If you @strong{need} to mention the version numbers of libraries which
940 are distributed separately from the package which contains this program,
941 you can do so by printing an additional line of version info for each
942 library you want to mention. Use the same format for these lines as for
945 Please do not mention all of the libraries that the program uses ``just
946 for completeness''---that would produce a lot of unhelpful clutter.
947 Please mention library version numbers only if you find in practice that
948 they are very important to you in debugging.
950 The following line, after the version number line or lines, should be a
951 copyright notice. If more than one copyright notice is called for, put
952 each on a separate line.
954 Next should follow a brief statement that the program is free software,
955 and that users are free to copy and change it on certain conditions. If
956 the program is covered by the GNU GPL, say so here. Also mention that
957 there is no warranty, to the extent permitted by law.
959 It is ok to finish the output with a list of the major authors of the
960 program, as a way of giving credit.
962 Here's an example of output that follows these rules:
966 Copyright (C) 1996 Free Software Foundation, Inc.
967 GNU Emacs comes with NO WARRANTY,
968 to the extent permitted by law.
969 You may redistribute copies of GNU Emacs
970 under the terms of the GNU General Public License.
971 For more information about these matters,
972 see the files named COPYING.
975 You should adapt this to your program, of course, filling in the proper
976 year, copyright holder, name of program, and the references to
977 distribution terms, and changing the rest of the wording as necessary.
979 This copyright notice only needs to mention the most recent year in
980 which changes were made---there's no need to list the years for previous
981 versions' changes. You don't have to mention the name of the program in
982 these notices, if that is inconvenient, since it appeared in the first
983 line. (The rules are different for copyright notices in source files;
984 see @ref{Copyright Notices,,,maintain,Information for GNU Maintainers}.)
986 Translations of the above lines must preserve the validity of the
987 copyright notices (@pxref{Internationalization}). If the translation's
988 character set supports it, the @samp{(C)} should be replaced with the
989 copyright symbol, as follows:
992 (the official copyright symbol, which is the letter C in a circle);
998 Write the word ``Copyright'' exactly like that, in English. Do not
999 translate it into another language. International treaties recognize
1000 the English word ``Copyright''; translations into other languages do not
1001 have legal significance.
1004 @cindex @samp{--help} option
1006 This option should output brief documentation for how to invoke the
1007 program, on standard output, then exit successfully. Other options and
1008 arguments should be ignored once this is seen, and the program should
1009 not perform its normal function.
1011 @cindex address for bug reports
1013 Near the end of the @samp{--help} option's output there should be a line
1014 that says where to mail bug reports. It should have this format:
1017 Report bugs to @var{mailing-address}.
1022 @section Table of Long Options
1023 @cindex long option names
1024 @cindex table of long options
1026 Here is a table of long options used by GNU programs. It is surely
1027 incomplete, but we aim to list all the options that a new program might
1028 want to be compatible with. If you use names not already in the table,
1029 please send @email{bug-standards@@gnu.org} a list of them, with their
1030 meanings, so we can update the table.
1032 @c Please leave newlines between items in this table; it's much easier
1033 @c to update when it isn't completely squashed together and unreadable.
1034 @c When there is more than one short option for a long option name, put
1035 @c a semicolon between the lists of the programs that use them, not a
1036 @c period. --friedman
1040 @samp{-N} in @code{tar}.
1043 @samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
1044 and @code{unexpand}.
1047 @samp{-a} in @code{diff}.
1050 @samp{-A} in @code{ls}.
1053 @samp{-a} in @code{etags}, @code{tee}, @code{time};
1054 @samp{-r} in @code{tar}.
1057 @samp{-a} in @code{cp}.
1060 @samp{-n} in @code{shar}.
1063 @samp{-l} in @code{m4}.
1066 @samp{-a} in @code{diff}.
1069 @samp{-v} in @code{gawk}.
1078 @samp{-a} in @code{recode}.
1081 @samp{-a} in @code{wdiff}.
1083 @item auto-reference
1084 @samp{-A} in @code{ptx}.
1087 @samp{-n} in @code{wdiff}.
1090 For server programs, run in the background.
1092 @item backward-search
1093 @samp{-B} in @code{ctags}.
1096 @samp{-f} in @code{shar}.
1105 @samp{-b} in @code{tac}.
1108 @samp{-b} in @code{cpio} and @code{diff}.
1111 @samp{-b} in @code{shar}.
1114 Used in @code{cpio} and @code{tar}.
1117 @samp{-b} in @code{head} and @code{tail}.
1120 @samp{-b} in @code{ptx}.
1123 Used in various programs to make output shorter.
1126 @samp{-c} in @code{head}, @code{split}, and @code{tail}.
1129 @samp{-C} in @code{etags}.
1132 @samp{-A} in @code{tar}.
1135 Used in various programs to specify the directory to use.
1138 @samp{-c} in @code{chgrp} and @code{chown}.
1141 @samp{-F} in @code{ls}.
1144 @samp{-c} in @code{recode}.
1147 @samp{-c} in @code{su};
1151 @samp{-d} in @code{tar}.
1154 Used in @code{gawk}.
1157 @samp{-Z} in @code{tar} and @code{shar}.
1160 @samp{-A} in @code{tar}.
1163 @samp{-w} in @code{tar}.
1166 Used in @code{diff}.
1169 @samp{-W copyleft} in @code{gawk}.
1172 @samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
1173 @samp{-W copyright} in @code{gawk}.
1179 @samp{-q} in @code{who}.
1182 @samp{-l} in @code{du}.
1185 Used in @code{tar} and @code{cpio}.
1188 @samp{-c} in @code{shar}.
1191 @samp{-x} in @code{ctags}.
1194 @samp{-d} in @code{touch}.
1197 @samp{-d} in Make and @code{m4};
1201 @samp{-D} in @code{m4}.
1204 @samp{-d} in Bison and @code{ctags}.
1207 @samp{-D} in @code{tar}.
1210 @samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
1211 @code{ls}, and @code{tar}.
1213 @item dereference-args
1214 @samp{-D} in @code{du}.
1217 Specify an I/O device (special file name).
1220 @samp{-d} in @code{recode}.
1222 @item dictionary-order
1223 @samp{-d} in @code{look}.
1226 @samp{-d} in @code{tar}.
1229 @samp{-n} in @code{csplit}.
1232 Specify the directory to use, in various programs. In @code{ls}, it
1233 means to show directories themselves rather than their contents. In
1234 @code{rm} and @code{ln}, it means to not treat links to directories
1238 @samp{-x} in @code{strip}.
1240 @item discard-locals
1241 @samp{-X} in @code{strip}.
1247 @samp{-e} in @code{diff}.
1249 @item elide-empty-files
1250 @samp{-z} in @code{csplit}.
1253 @samp{-x} in @code{wdiff}.
1256 @samp{-z} in @code{wdiff}.
1258 @item entire-new-file
1259 @samp{-N} in @code{diff}.
1261 @item environment-overrides
1265 @samp{-e} in @code{xargs}.
1271 Used in @code{makeinfo}.
1274 @samp{-o} in @code{m4}.
1277 @samp{-b} in @code{ls}.
1280 @samp{-X} in @code{tar}.
1286 @samp{-x} in @code{xargs}.
1289 @samp{-e} in @code{unshar}.
1292 @samp{-t} in @code{diff}.
1295 @samp{-e} in @code{sed}.
1298 @samp{-g} in @code{nm}.
1301 @samp{-i} in @code{cpio};
1302 @samp{-x} in @code{tar}.
1305 @samp{-f} in @code{finger}.
1308 @samp{-f} in @code{su}.
1310 @item fatal-warnings
1311 @samp{-E} in @code{m4}.
1314 @samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
1315 @samp{-n} in @code{sed};
1316 @samp{-r} in @code{touch}.
1318 @item field-separator
1319 @samp{-F} in @code{gawk}.
1325 @samp{-F} in @code{ls}.
1328 @samp{-T} in @code{tar}.
1331 Used in @code{makeinfo}.
1333 @item flag-truncation
1334 @samp{-F} in @code{ptx}.
1336 @item fixed-output-files
1340 @samp{-f} in @code{tail}.
1342 @item footnote-style
1343 Used in @code{makeinfo}.
1346 @samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
1349 @samp{-F} in @code{shar}.
1352 For server programs, run in the foreground;
1353 in other words, don't do anything special to run the server
1357 Used in @code{ls}, @code{time}, and @code{ptx}.
1360 @samp{-F} in @code{m4}.
1366 @samp{-g} in @code{ptx}.
1369 @samp{-x} in @code{tar}.
1372 @samp{-i} in @code{ul}.
1375 @samp{-g} in @code{recode}.
1378 @samp{-g} in @code{install}.
1381 @samp{-z} in @code{tar} and @code{shar}.
1384 @samp{-H} in @code{m4}.
1387 @samp{-h} in @code{objdump} and @code{recode}
1390 @samp{-H} in @code{who}.
1393 Used to ask for brief usage information.
1395 @item here-delimiter
1396 @samp{-d} in @code{shar}.
1398 @item hide-control-chars
1399 @samp{-q} in @code{ls}.
1402 In @code{makeinfo}, output HTML.
1405 @samp{-u} in @code{who}.
1408 @samp{-D} in @code{diff}.
1411 @samp{-I} in @code{ls};
1412 @samp{-x} in @code{recode}.
1414 @item ignore-all-space
1415 @samp{-w} in @code{diff}.
1417 @item ignore-backups
1418 @samp{-B} in @code{ls}.
1420 @item ignore-blank-lines
1421 @samp{-B} in @code{diff}.
1424 @samp{-f} in @code{look} and @code{ptx};
1425 @samp{-i} in @code{diff} and @code{wdiff}.
1431 @samp{-i} in @code{ptx}.
1433 @item ignore-indentation
1434 @samp{-I} in @code{etags}.
1436 @item ignore-init-file
1439 @item ignore-interrupts
1440 @samp{-i} in @code{tee}.
1442 @item ignore-matching-lines
1443 @samp{-I} in @code{diff}.
1445 @item ignore-space-change
1446 @samp{-b} in @code{diff}.
1449 @samp{-i} in @code{tar}.
1452 @samp{-i} in @code{etags};
1453 @samp{-I} in @code{m4}.
1459 @samp{-G} in @code{tar}.
1462 @samp{-i}, @samp{-l}, and @samp{-m} in Finger.
1465 In some programs, specify the name of the file to read as the user's
1469 @samp{-i} in @code{expand}.
1472 @samp{-T} in @code{diff}.
1475 @samp{-i} in @code{ls}.
1478 @samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
1479 @samp{-e} in @code{m4};
1480 @samp{-p} in @code{xargs};
1481 @samp{-w} in @code{tar}.
1484 @samp{-p} in @code{shar}.
1499 @samp{-k} in @code{csplit}.
1502 @samp{-k} in @code{du} and @code{ls}.
1505 @samp{-l} in @code{etags}.
1508 @samp{-l} in @code{wdiff}.
1510 @item level-for-gzip
1511 @samp{-g} in @code{shar}.
1514 @samp{-C} in @code{split}.
1517 Used in @code{split}, @code{head}, and @code{tail}.
1520 @samp{-l} in @code{cpio}.
1524 Used in @code{gawk}.
1527 @samp{-t} in @code{cpio};
1528 @samp{-l} in @code{recode}.
1531 @samp{-t} in @code{tar}.
1534 @samp{-N} in @code{ls}.
1543 Used in @code{uname}.
1546 @samp{-M} in @code{ptx}.
1549 @samp{-m} in @code{hello} and @code{uname}.
1551 @item make-directories
1552 @samp{-d} in @code{cpio}.
1561 @samp{-n} in @code{xargs}.
1564 @samp{-n} in @code{xargs}.
1567 @samp{-l} in @code{xargs}.
1573 @samp{-P} in @code{xargs}.
1576 @samp{-T} in @code{who}.
1579 @samp{-T} in @code{who}.
1582 @samp{-d} in @code{diff}.
1584 @item mixed-uuencode
1585 @samp{-M} in @code{shar}.
1588 @samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
1590 @item modification-time
1591 @samp{-m} in @code{tar}.
1594 @samp{-M} in @code{tar}.
1600 @samp{-L} in @code{m4}.
1603 @samp{-a} in @code{shar}.
1608 @item no-builtin-rules
1611 @item no-character-count
1612 @samp{-w} in @code{shar}.
1614 @item no-check-existing
1615 @samp{-x} in @code{shar}.
1618 @samp{-3} in @code{wdiff}.
1621 @samp{-c} in @code{touch}.
1624 @samp{-D} in @code{etags}.
1627 @samp{-1} in @code{wdiff}.
1629 @item no-dereference
1630 @samp{-d} in @code{cp}.
1633 @samp{-2} in @code{wdiff}.
1642 @samp{-P} in @code{shar}.
1645 @samp{-e} in @code{gprof}.
1648 @samp{-R} in @code{etags}.
1651 @samp{-p} in @code{nm}.
1654 Don't print a startup splash screen.
1657 Used in @code{makeinfo}.
1660 @samp{-a} in @code{gprof}.
1663 @samp{-E} in @code{gprof}.
1666 @samp{-m} in @code{shar}.
1669 Used in @code{makeinfo}.
1672 Used in @code{emacsclient}.
1675 Used in various programs to inhibit warnings.
1678 @samp{-n} in @code{info}.
1681 @samp{-n} in @code{uname}.
1684 @samp{-f} in @code{cpio}.
1687 @samp{-n} in @code{objdump}.
1690 @samp{-0} in @code{xargs}.
1693 @samp{-n} in @code{cat}.
1695 @item number-nonblank
1696 @samp{-b} in @code{cat}.
1699 @samp{-n} in @code{nm}.
1701 @item numeric-uid-gid
1702 @samp{-n} in @code{cpio} and @code{ls}.
1708 @samp{-o} in @code{tar}.
1713 @item one-file-system
1714 @samp{-l} in @code{tar}, @code{cp}, and @code{du}.
1717 @samp{-o} in @code{ptx}.
1720 @samp{-f} in @code{gprof}.
1723 @samp{-F} in @code{gprof}.
1726 @samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
1727 @code{fdmountd}, and @code{fdumount}.
1730 In various programs, specify the output file name.
1733 @samp{-o} in @code{shar}.
1736 @samp{-o} in @code{rm}.
1739 @samp{-c} in @code{unshar}.
1742 @samp{-o} in @code{install}.
1745 @samp{-l} in @code{diff}.
1747 @item paragraph-indent
1748 Used in @code{makeinfo}.
1751 @samp{-p} in @code{mkdir} and @code{rmdir}.
1754 @samp{-p} in @code{ul}.
1757 @samp{-p} in @code{cpio}.
1760 @samp{-P} in @code{finger}.
1763 @samp{-c} in @code{cpio} and @code{tar}.
1766 Used in @code{gawk}.
1768 @item prefix-builtins
1769 @samp{-P} in @code{m4}.
1772 @samp{-f} in @code{csplit}.
1775 Used in @code{tar} and @code{cp}.
1777 @item preserve-environment
1778 @samp{-p} in @code{su}.
1780 @item preserve-modification-time
1781 @samp{-m} in @code{cpio}.
1783 @item preserve-order
1784 @samp{-s} in @code{tar}.
1786 @item preserve-permissions
1787 @samp{-p} in @code{tar}.
1790 @samp{-l} in @code{diff}.
1793 @samp{-L} in @code{cmp}.
1795 @item print-data-base
1798 @item print-directory
1801 @item print-file-name
1802 @samp{-o} in @code{nm}.
1805 @samp{-s} in @code{nm}.
1808 @samp{-p} in @code{wdiff}.
1811 @samp{-p} in @code{ed}.
1814 Specify an HTTP proxy.
1817 @samp{-X} in @code{shar}.
1823 Used in many programs to inhibit the usual output. Every
1824 program accepting @samp{--quiet} should accept @samp{--silent} as a
1828 @samp{-Q} in @code{shar}
1831 @samp{-Q} in @code{ls}.
1834 @samp{-n} in @code{diff}.
1837 Used in @code{gawk}.
1839 @item read-full-blocks
1840 @samp{-B} in @code{tar}.
1849 @samp{-R} in @code{tar}.
1852 Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
1855 @item reference-limit
1856 Used in @code{makeinfo}.
1859 @samp{-r} in @code{ptx}.
1862 @samp{-r} in @code{tac} and @code{etags}.
1865 @samp{-r} in @code{uname}.
1868 @samp{-R} in @code{m4}.
1871 @samp{-r} in @code{objdump}.
1874 @samp{-r} in @code{cpio}.
1877 @samp{-i} in @code{xargs}.
1879 @item report-identical-files
1880 @samp{-s} in @code{diff}.
1882 @item reset-access-time
1883 @samp{-a} in @code{cpio}.
1886 @samp{-r} in @code{ls} and @code{nm}.
1889 @samp{-f} in @code{diff}.
1891 @item right-side-defs
1892 @samp{-R} in @code{ptx}.
1895 @samp{-s} in @code{tar}.
1897 @item same-permissions
1898 @samp{-p} in @code{tar}.
1901 @samp{-g} in @code{stty}.
1906 @item sentence-regexp
1907 @samp{-S} in @code{ptx}.
1910 @samp{-S} in @code{du}.
1913 @samp{-s} in @code{tac}.
1916 Used by @code{recode} to chose files or pipes for sequencing passes.
1919 @samp{-s} in @code{su}.
1922 @samp{-A} in @code{cat}.
1924 @item show-c-function
1925 @samp{-p} in @code{diff}.
1928 @samp{-E} in @code{cat}.
1930 @item show-function-line
1931 @samp{-F} in @code{diff}.
1934 @samp{-T} in @code{cat}.
1937 Used in many programs to inhibit the usual output.
1938 Every program accepting
1939 @samp{--silent} should accept @samp{--quiet} as a synonym.
1942 @samp{-s} in @code{ls}.
1945 Specify a file descriptor for a network server to use for its socket,
1946 instead of opening and binding a new socket. This provides a way to
1947 run, in a non-privileged process, a server that normally needs a
1948 reserved port number.
1954 @samp{-W source} in @code{gawk}.
1957 @samp{-S} in @code{tar}.
1959 @item speed-large-files
1960 @samp{-H} in @code{diff}.
1963 @samp{-E} in @code{unshar}.
1965 @item split-size-limit
1966 @samp{-L} in @code{shar}.
1969 @samp{-s} in @code{cat}.
1972 @samp{-w} in @code{wdiff}.
1975 @samp{-y} in @code{wdiff}.
1978 Used in @code{tar} and @code{diff} to specify which file within
1979 a directory to start processing with.
1982 @samp{-s} in @code{wdiff}.
1984 @item stdin-file-list
1985 @samp{-S} in @code{shar}.
1991 @samp{-s} in @code{recode}.
1994 @samp{-s} in @code{install}.
1997 @samp{-s} in @code{strip}.
2000 @samp{-S} in @code{strip}.
2003 @samp{-s} in @code{shar}.
2006 @samp{-S} in @code{cp}, @code{ln}, @code{mv}.
2009 @samp{-b} in @code{csplit}.
2012 @samp{-s} in @code{gprof}.
2015 @samp{-s} in @code{du}.
2018 @samp{-s} in @code{ln}.
2021 Used in GDB and @code{objdump}.
2024 @samp{-s} in @code{m4}.
2027 @samp{-s} in @code{uname}.
2030 @samp{-t} in @code{expand} and @code{unexpand}.
2033 @samp{-T} in @code{ls}.
2036 @samp{-T} in @code{tput} and @code{ul}.
2037 @samp{-t} in @code{wdiff}.
2040 @samp{-a} in @code{diff}.
2043 @samp{-T} in @code{shar}.
2046 Used in @code{ls} and @code{touch}.
2049 Specify how long to wait before giving up on some operation.
2052 @samp{-O} in @code{tar}.
2055 @samp{-c} in @code{du}.
2058 @samp{-t} in Make, @code{ranlib}, and @code{recode}.
2061 @samp{-t} in @code{m4}.
2064 @samp{-t} in @code{hello};
2065 @samp{-W traditional} in @code{gawk};
2066 @samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
2072 @samp{-t} in @code{ctags}.
2074 @item typedefs-and-c++
2075 @samp{-T} in @code{ctags}.
2078 @samp{-t} in @code{ptx}.
2081 @samp{-z} in @code{tar}.
2084 @samp{-u} in @code{cpio}.
2087 @samp{-U} in @code{m4}.
2089 @item undefined-only
2090 @samp{-u} in @code{nm}.
2093 @samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
2096 Used in @code{gawk}; same as @samp{--help}.
2099 @samp{-B} in @code{shar}.
2101 @item vanilla-operation
2102 @samp{-V} in @code{shar}.
2105 Print more information about progress. Many programs support this.
2108 @samp{-W} in @code{tar}.
2111 Print the version number.
2113 @item version-control
2114 @samp{-V} in @code{cp}, @code{ln}, @code{mv}.
2117 @samp{-v} in @code{ctags}.
2120 @samp{-V} in @code{tar}.
2125 @item whole-size-limit
2126 @samp{-l} in @code{shar}.
2129 @samp{-w} in @code{ls} and @code{ptx}.
2132 @samp{-W} in @code{ptx}.
2135 @samp{-T} in @code{who}.
2138 @samp{-z} in @code{gprof}.
2142 @section Memory Usage
2143 @cindex memory usage
2145 If a program typically uses just a few meg of memory, don't bother making any
2146 effort to reduce memory usage. For example, if it is impractical for
2147 other reasons to operate on files more than a few meg long, it is
2148 reasonable to read entire input files into memory to operate on them.
2150 However, for programs such as @code{cat} or @code{tail}, that can
2151 usefully operate on very large files, it is important to avoid using a
2152 technique that would artificially limit the size of files it can handle.
2153 If a program works by lines and could be applied to arbitrary
2154 user-supplied input files, it should keep only a line in memory, because
2155 this is not very hard and users will want to be able to operate on input
2156 files that are bigger than will fit in memory all at once.
2158 If your program creates complicated data structures, just make them in
2159 memory and give a fatal error if @code{malloc} returns zero.
2165 Programs should be prepared to operate when @file{/usr} and @file{/etc}
2166 are read-only file systems. Thus, if the program manages log files,
2167 lock files, backup files, score files, or any other files which are
2168 modified for internal purposes, these files should not be stored in
2169 @file{/usr} or @file{/etc}.
2171 There are two exceptions. @file{/etc} is used to store system
2172 configuration information; it is reasonable for a program to modify
2173 files in @file{/etc} when its job is to update the system configuration.
2174 Also, if the user explicitly asks to modify one file in a directory, it
2175 is reasonable for the program to store other files in the same
2179 @chapter Making The Best Use of C
2181 This chapter provides advice on how best to use the C language
2182 when writing GNU software.
2185 * Formatting:: Formatting Your Source Code
2186 * Comments:: Commenting Your Work
2187 * Syntactic Conventions:: Clean Use of C Constructs
2188 * Names:: Naming Variables, Functions, and Files
2189 * System Portability:: Portability between different operating systems
2190 * CPU Portability:: Supporting the range of CPU types
2191 * System Functions:: Portability and ``standard'' library functions
2192 * Internationalization:: Techniques for internationalization
2193 * Character Set:: Use ASCII by default.
2194 * Quote Characters:: Use `...' in the C locale.
2195 * Mmap:: How you can safely use @code{mmap}.
2199 @section Formatting Your Source Code
2200 @cindex formatting source code
2203 @cindex braces, in C source
2204 It is important to put the open-brace that starts the body of a C
2205 function in column one, so that they will start a defun. Several
2206 tools look for open-braces in column one to find the beginnings of C
2207 functions. These tools will not work on code not formatted that way.
2209 Avoid putting open-brace, open-parenthesis or open-bracket in column
2210 one when they are inside a function, so that they won't start a defun.
2211 The open-brace that starts a @code{struct} body can go in column one
2212 if you find it useful to treat that definition as a defun.
2214 It is also important for function definitions to start the name of the
2215 function in column one. This helps people to search for function
2216 definitions, and may also help certain tools recognize them. Thus,
2217 using Standard C syntax, the format is this:
2221 concat (char *s1, char *s2)
2228 or, if you want to use traditional C syntax, format the definition like
2233 concat (s1, s2) /* Name starts in column one here */
2235 @{ /* Open brace in column one here */
2240 In Standard C, if the arguments don't fit nicely on one line,
2245 lots_of_args (int an_integer, long a_long, short a_short,
2246 double a_double, float a_float)
2250 The rest of this section gives our recommendations for other aspects of
2251 C formatting style, which is also the default style of the @code{indent}
2252 program in version 1.2 and newer. It corresponds to the options
2255 -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2256 -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2259 We don't think of these recommendations as requirements, because it
2260 causes no problems for users if two different programs have different
2263 But whatever style you use, please use it consistently, since a mixture
2264 of styles within one program tends to look ugly. If you are
2265 contributing changes to an existing program, please follow the style of
2268 For the body of the function, our recommended style looks like this:
2280 return ++x + bar ();
2284 @cindex spaces before open-paren
2285 We find it easier to read a program when it has spaces before the
2286 open-parentheses and after the commas. Especially after the commas.
2288 When you split an expression into multiple lines, split it
2289 before an operator, not after one. Here is the right way:
2291 @cindex expressions, splitting
2293 if (foo_this_is_long && bar > win (x, y, z)
2294 && remaining_condition)
2297 Try to avoid having two operators of different precedence at the same
2298 level of indentation. For example, don't write this:
2301 mode = (inmode[j] == VOIDmode
2302 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2303 ? outmode[j] : inmode[j]);
2306 Instead, use extra parentheses so that the indentation shows the nesting:
2309 mode = ((inmode[j] == VOIDmode
2310 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2311 ? outmode[j] : inmode[j]);
2314 Insert extra parentheses so that Emacs will indent the code properly.
2315 For example, the following indentation looks nice if you do it by hand,
2318 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2319 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2323 but Emacs would alter it. Adding a set of parentheses produces
2324 something that looks equally nice, and which Emacs will preserve:
2327 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2328 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2331 Format do-while statements like this:
2343 Please use formfeed characters (control-L) to divide the program into
2344 pages at logical places (but not within a function). It does not matter
2345 just how long the pages are, since they do not have to fit on a printed
2346 page. The formfeeds should appear alone on lines by themselves.
2349 @section Commenting Your Work
2352 Every program should start with a comment saying briefly what it is for.
2353 Example: @samp{fmt - filter for simple filling of text}. This comment
2354 should be at the top of the source file containing the @samp{main}
2355 function of the program.
2357 Also, please write a brief comment at the start of each source file,
2358 with the file name and a line or two about the overall purpose of the
2361 Please write the comments in a GNU program in English, because English
2362 is the one language that nearly all programmers in all countries can
2363 read. If you do not write English well, please write comments in
2364 English as well as you can, then ask other people to help rewrite them.
2365 If you can't write comments in English, please find someone to work with
2366 you and translate your comments into English.
2368 Please put a comment on each function saying what the function does,
2369 what sorts of arguments it gets, and what the possible values of
2370 arguments mean and are used for. It is not necessary to duplicate in
2371 words the meaning of the C argument declarations, if a C type is being
2372 used in its customary fashion. If there is anything nonstandard about
2373 its use (such as an argument of type @code{char *} which is really the
2374 address of the second character of a string, not the first), or any
2375 possible values that would not work the way one would expect (such as,
2376 that strings containing newlines are not guaranteed to work), be sure
2379 Also explain the significance of the return value, if there is one.
2381 Please put two spaces after the end of a sentence in your comments, so
2382 that the Emacs sentence commands will work. Also, please write
2383 complete sentences and capitalize the first word. If a lower-case
2384 identifier comes at the beginning of a sentence, don't capitalize it!
2385 Changing the spelling makes it a different identifier. If you don't
2386 like starting a sentence with a lower case letter, write the sentence
2387 differently (e.g., ``The identifier lower-case is @dots{}'').
2389 The comment on a function is much clearer if you use the argument
2390 names to speak about the argument values. The variable name itself
2391 should be lower case, but write it in upper case when you are speaking
2392 about the value rather than the variable itself. Thus, ``the inode
2393 number NODE_NUM'' rather than ``an inode''.
2395 There is usually no purpose in restating the name of the function in
2396 the comment before it, because the reader can see that for himself.
2397 There might be an exception when the comment is so long that the function
2398 itself would be off the bottom of the screen.
2400 There should be a comment on each static variable as well, like this:
2403 /* Nonzero means truncate lines in the display;
2404 zero means continue them. */
2408 @cindex conditionals, comments for
2409 @cindex @code{#endif}, commenting
2410 Every @samp{#endif} should have a comment, except in the case of short
2411 conditionals (just a few lines) that are not nested. The comment should
2412 state the condition of the conditional that is ending, @emph{including
2413 its sense}. @samp{#else} should have a comment describing the condition
2414 @emph{and sense} of the code that follows. For example:
2422 #endif /* not foo */
2432 but, by contrast, write the comments this way for a @samp{#ifndef}:
2445 #endif /* not foo */
2449 @node Syntactic Conventions
2450 @section Clean Use of C Constructs
2451 @cindex syntactic conventions
2453 @cindex implicit @code{int}
2454 @cindex function argument, declaring
2455 Please explicitly declare the types of all objects. For example, you
2456 should explicitly declare all arguments to functions, and you should
2457 declare functions to return @code{int} rather than omitting the
2460 @cindex compiler warnings
2461 @cindex @samp{-Wall} compiler option
2462 Some programmers like to use the GCC @samp{-Wall} option, and change the
2463 code whenever it issues a warning. If you want to do this, then do.
2464 Other programmers prefer not to use @samp{-Wall}, because it gives
2465 warnings for valid and legitimate code which they do not want to change.
2466 If you want to do this, then do. The compiler should be your servant,
2469 Declarations of external functions and functions to appear later in the
2470 source file should all go in one place near the beginning of the file
2471 (somewhere before the first function definition in the file), or else
2472 should go in a header file. Don't put @code{extern} declarations inside
2475 @cindex temporary variables
2476 It used to be common practice to use the same local variables (with
2477 names like @code{tem}) over and over for different values within one
2478 function. Instead of doing this, it is better to declare a separate local
2479 variable for each distinct purpose, and give it a name which is
2480 meaningful. This not only makes programs easier to understand, it also
2481 facilitates optimization by good compilers. You can also move the
2482 declaration of each local variable into the smallest scope that includes
2483 all its uses. This makes the program even cleaner.
2485 Don't use local variables or parameters that shadow global identifiers.
2487 @cindex multiple variables in a line
2488 Don't declare multiple variables in one declaration that spans lines.
2489 Start a new declaration on each line, instead. For example, instead
2515 (If they are global variables, each should have a comment preceding it
2518 When you have an @code{if}-@code{else} statement nested in another
2519 @code{if} statement, always put braces around the @code{if}-@code{else}.
2520 Thus, never write like this:
2543 If you have an @code{if} statement nested inside of an @code{else}
2544 statement, either write @code{else if} on one line, like this,
2554 with its @code{then}-part indented like the preceding @code{then}-part,
2555 or write the nested @code{if} within braces like this:
2567 Don't declare both a structure tag and variables or typedefs in the
2568 same declaration. Instead, declare the structure tag separately
2569 and then use it to declare the variables or typedefs.
2571 Try to avoid assignments inside @code{if}-conditions (assignments
2572 inside @code{while}-conditions are ok). For example, don't write
2576 if ((foo = (char *) malloc (sizeof *foo)) == 0)
2577 fatal ("virtual memory exhausted");
2581 instead, write this:
2584 foo = (char *) malloc (sizeof *foo);
2586 fatal ("virtual memory exhausted");
2590 Don't make the program ugly to placate @code{lint}. Please don't insert any
2591 casts to @code{void}. Zero without a cast is perfectly fine as a null
2592 pointer constant, except when calling a varargs function.
2595 @section Naming Variables, Functions, and Files
2597 @cindex names of variables, functions, and files
2598 The names of global variables and functions in a program serve as
2599 comments of a sort. So don't choose terse names---instead, look for
2600 names that give useful information about the meaning of the variable or
2601 function. In a GNU program, names should be English, like other
2604 Local variable names can be shorter, because they are used only within
2605 one context, where (presumably) comments explain their purpose.
2607 Try to limit your use of abbreviations in symbol names. It is ok to
2608 make a few abbreviations, explain what they mean, and then use them
2609 frequently, but don't use lots of obscure abbreviations.
2611 Please use underscores to separate words in a name, so that the Emacs
2612 word commands can be useful within them. Stick to lower case; reserve
2613 upper case for macros and @code{enum} constants, and for name-prefixes
2614 that follow a uniform convention.
2616 For example, you should use names like @code{ignore_space_change_flag};
2617 don't use names like @code{iCantReadThis}.
2619 Variables that indicate whether command-line options have been
2620 specified should be named after the meaning of the option, not after
2621 the option-letter. A comment should state both the exact meaning of
2622 the option and its letter. For example,
2626 /* Ignore changes in horizontal whitespace (-b). */
2627 int ignore_space_change_flag;
2631 When you want to define names with constant integer values, use
2632 @code{enum} rather than @samp{#define}. GDB knows about enumeration
2635 @cindex file-name limitations
2637 You might want to make sure that none of the file names would conflict
2638 if the files were loaded onto an MS-DOS file system which shortens the
2639 names. You can use the program @code{doschk} to test for this.
2641 Some GNU programs were designed to limit themselves to file names of 14
2642 characters or less, to avoid file name conflicts if they are read into
2643 older System V systems. Please preserve this feature in the existing
2644 GNU programs that have it, but there is no need to do this in new GNU
2645 programs. @code{doschk} also reports file names longer than 14
2648 @node System Portability
2649 @section Portability between System Types
2650 @cindex portability, between system types
2652 In the Unix world, ``portability'' refers to porting to different Unix
2653 versions. For a GNU program, this kind of portability is desirable, but
2656 The primary purpose of GNU software is to run on top of the GNU kernel,
2657 compiled with the GNU C compiler, on various types of @sc{cpu}. So the
2658 kinds of portability that are absolutely necessary are quite limited.
2659 But it is important to support Linux-based GNU systems, since they
2660 are the form of GNU that is popular.
2662 Beyond that, it is good to support the other free operating systems
2663 (*BSD), and it is nice to support other Unix-like systems if you want
2664 to. Supporting a variety of Unix-like systems is desirable, although
2665 not paramount. It is usually not too hard, so you may as well do it.
2666 But you don't have to consider it an obligation, if it does turn out to
2670 The easiest way to achieve portability to most Unix-like systems is to
2671 use Autoconf. It's unlikely that your program needs to know more
2672 information about the host platform than Autoconf can provide, simply
2673 because most of the programs that need such knowledge have already been
2676 Avoid using the format of semi-internal data bases (e.g., directories)
2677 when there is a higher-level alternative (@code{readdir}).
2679 @cindex non-@sc{posix} systems, and portability
2680 As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
2681 and older Macintosh systems, supporting them is often a lot of work.
2682 When that is the case, it is better to spend your time adding features
2683 that will be useful on GNU and GNU/Linux, rather than on supporting
2684 other incompatible systems.
2686 If you do support Windows, please do not abbreviate it as ``win''. In
2687 hacker terminology, calling something a ``win'' is a form of praise.
2688 You're free to praise Microsoft Windows on your own if you want, but
2689 please don't do this in GNU packages. Instead of abbreviating
2690 ``Windows'' to ``un'', you can write it in full or abbreviate it to
2691 ``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in
2692 file names of Windows-specific files, but the macro for Windows
2693 conditionals is called @code{WINDOWSNT}.
2695 It is a good idea to define the ``feature test macro''
2696 @code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
2697 or GNU/Linux, this will enable the declarations of GNU library extension
2698 functions, and that will usually give you a compiler error message if
2699 you define the same function names in some other way in your program.
2700 (You don't have to actually @emph{use} these functions, if you prefer
2701 to make the program more portable to other systems.)
2703 But whether or not you use these GNU extensions, you should avoid
2704 using their names for any other meanings. Doing so would make it hard
2705 to move your code into other GNU programs.
2707 @node CPU Portability
2708 @section Portability between @sc{cpu}s
2710 @cindex data types, and portability
2711 @cindex portability, and data types
2712 Even GNU systems will differ because of differences among @sc{cpu}
2713 types---for example, difference in byte ordering and alignment
2714 requirements. It is absolutely essential to handle these differences.
2715 However, don't make any effort to cater to the possibility that an
2716 @code{int} will be less than 32 bits. We don't support 16-bit machines
2719 Similarly, don't make any effort to cater to the possibility that
2720 @code{long} will be smaller than predefined types like @code{size_t}.
2721 For example, the following code is ok:
2724 printf ("size = %lu\n", (unsigned long) sizeof array);
2725 printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2728 1989 Standard C requires this to work, and we know of only one
2729 counterexample: 64-bit programs on Microsoft Windows. We will
2730 leave it to those who want to port GNU programs to that environment
2731 to figure out how to do it.
2733 Predefined file-size types like @code{off_t} are an exception: they are
2734 longer than @code{long} on many platforms, so code like the above won't
2735 work with them. One way to print an @code{off_t} value portably is to
2736 print its digits yourself, one by one.
2738 Don't assume that the address of an @code{int} object is also the
2739 address of its least-significant byte. This is false on big-endian
2740 machines. Thus, don't make the following mistake:
2745 while ((c = getchar ()) != EOF)
2746 write (file_descriptor, &c, 1);
2749 @noindent Instead, use @code{unsigned char} as follows. (The @code{unsigned}
2750 is for portability to unusual systems where @code{char} is signed and
2751 where there is integer overflow checking.)
2755 while ((c = getchar ()) != EOF)
2757 unsigned char u = c;
2758 write (file_descriptor, &u, 1);
2762 It used to be ok to not worry about the difference between pointers
2763 and integers when passing arguments to functions. However, on most
2764 modern 64-bit machines pointers are wider than @code{int}.
2765 Conversely, integer types like @code{long long int} and @code{off_t}
2766 are wider than pointers on most modern 32-bit machines. Hence it's
2767 often better nowadays to use prototypes to define functions whose
2768 argument types are not trivial.
2770 In particular, if functions accept varying argument counts or types
2771 they should be declared using prototypes containing @samp{...} and
2772 defined using @file{stdarg.h}. For an example of this, please see the
2773 @uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
2774 declares and defines the following function:
2777 /* Print a message with `fprintf (stderr, FORMAT, ...)';
2778 if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2779 If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
2781 void error (int status, int errnum, const char *format, ...);
2784 A simple way to use the Gnulib error module is to obtain the two
2785 source files @file{error.c} and @file{error.h} from the Gnulib library
2786 source code repository at
2787 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/}.
2788 Here's a sample use:
2795 char *program_name = "myprogram";
2798 xfopen (char const *name)
2800 FILE *fp = fopen (name, "r");
2802 error (1, errno, "cannot read %s", name);
2807 @cindex casting pointers to integers
2808 Avoid casting pointers to integers if you can. Such casts greatly
2809 reduce portability, and in most programs they are easy to avoid. In the
2810 cases where casting pointers to integers is essential---such as, a Lisp
2811 interpreter which stores type information as well as an address in one
2812 word---you'll have to make explicit provisions to handle different word
2813 sizes. You will also need to make provision for systems in which the
2814 normal range of addresses you can get from @code{malloc} starts far away
2817 @node System Functions
2818 @section Calling System Functions
2819 @cindex library functions, and portability
2820 @cindex portability, and library functions
2822 C implementations differ substantially. Standard C reduces but does
2823 not eliminate the incompatibilities; meanwhile, many GNU packages still
2824 support pre-standard compilers because this is not hard to do. This
2825 chapter gives recommendations for how to use the more-or-less standard C
2826 library functions to avoid unnecessary loss of portability.
2830 Don't use the return value of @code{sprintf}. It returns the number of
2831 characters written on some systems, but not on all systems.
2834 Be aware that @code{vfprintf} is not always available.
2837 @code{main} should be declared to return type @code{int}. It should
2838 terminate either by calling @code{exit} or by returning the integer
2839 status code; make sure it cannot ever return an undefined value.
2841 @cindex declaration for system functions
2843 Don't declare system functions explicitly.
2845 Almost any declaration for a system function is wrong on some system.
2846 To minimize conflicts, leave it to the system header files to declare
2847 system functions. If the headers don't declare a function, let it
2850 While it may seem unclean to use a function without declaring it, in
2851 practice this works fine for most system library functions on the
2852 systems where this really happens; thus, the disadvantage is only
2853 theoretical. By contrast, actual declarations have frequently caused
2857 If you must declare a system function, don't specify the argument types.
2858 Use an old-style declaration, not a Standard C prototype. The more you
2859 specify about the function, the more likely a conflict.
2862 In particular, don't unconditionally declare @code{malloc} or
2865 Most GNU programs use those functions just once, in functions
2866 conventionally named @code{xmalloc} and @code{xrealloc}. These
2867 functions call @code{malloc} and @code{realloc}, respectively, and
2870 Because @code{xmalloc} and @code{xrealloc} are defined in your program,
2871 you can declare them in other files without any risk of type conflict.
2873 On most systems, @code{int} is the same length as a pointer; thus, the
2874 calls to @code{malloc} and @code{realloc} work fine. For the few
2875 exceptional systems (mostly 64-bit machines), you can use
2876 @strong{conditionalized} declarations of @code{malloc} and
2877 @code{realloc}---or put these declarations in configuration files
2878 specific to those systems.
2880 @cindex string library functions
2882 The string functions require special treatment. Some Unix systems have
2883 a header file @file{string.h}; others have @file{strings.h}. Neither
2884 file name is portable. There are two things you can do: use Autoconf to
2885 figure out which file to include, or don't include either file.
2888 If you don't include either strings file, you can't get declarations for
2889 the string functions from the header file in the usual way.
2891 That causes less of a problem than you might think. The newer standard
2892 string functions should be avoided anyway because many systems still
2893 don't support them. The string functions you can use are these:
2896 strcpy strncpy strcat strncat
2897 strlen strcmp strncmp
2901 The copy and concatenate functions work fine without a declaration as
2902 long as you don't use their values. Using their values without a
2903 declaration fails on systems where the width of a pointer differs from
2904 the width of @code{int}, and perhaps in other cases. It is trivial to
2905 avoid using their values, so do that.
2907 The compare functions and @code{strlen} work fine without a declaration
2908 on most systems, possibly all the ones that GNU software runs on.
2909 You may find it necessary to declare them @strong{conditionally} on a
2912 The search functions must be declared to return @code{char *}. Luckily,
2913 there is no variation in the data type they return. But there is
2914 variation in their names. Some systems give these functions the names
2915 @code{index} and @code{rindex}; other systems use the names
2916 @code{strchr} and @code{strrchr}. Some systems support both pairs of
2917 names, but neither pair works on all systems.
2919 You should pick a single pair of names and use it throughout your
2920 program. (Nowadays, it is better to choose @code{strchr} and
2921 @code{strrchr} for new programs, since those are the standard
2922 names.) Declare both of those names as functions returning @code{char
2923 *}. On systems which don't support those names, define them as macros
2924 in terms of the other pair. For example, here is what to put at the
2925 beginning of your file (or in a header) if you want to use the names
2926 @code{strchr} and @code{strrchr} throughout:
2930 #define strchr index
2932 #ifndef HAVE_STRRCHR
2933 #define strrchr rindex
2941 Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
2942 macros defined in systems where the corresponding functions exist.
2943 One way to get them properly defined is to use Autoconf.
2945 @node Internationalization
2946 @section Internationalization
2947 @cindex internationalization
2950 GNU has a library called GNU gettext that makes it easy to translate the
2951 messages in a program into various languages. You should use this
2952 library in every program. Use English for the messages as they appear
2953 in the program, and let gettext provide the way to translate them into
2956 Using GNU gettext involves putting a call to the @code{gettext} macro
2957 around each string that might need translation---like this:
2960 printf (gettext ("Processing file `%s'..."));
2964 This permits GNU gettext to replace the string @code{"Processing file
2965 `%s'..."} with a translated version.
2967 Once a program uses gettext, please make a point of writing calls to
2968 @code{gettext} when you add new strings that call for translation.
2970 Using GNU gettext in a package involves specifying a @dfn{text domain
2971 name} for the package. The text domain name is used to separate the
2972 translations for this package from the translations for other packages.
2973 Normally, the text domain name should be the same as the name of the
2974 package---for example, @samp{coreutils} for the GNU core utilities.
2976 @cindex message text, and internationalization
2977 To enable gettext to work well, avoid writing code that makes
2978 assumptions about the structure of words or sentences. When you want
2979 the precise text of a sentence to vary depending on the data, use two or
2980 more alternative string constants each containing a complete sentences,
2981 rather than inserting conditionalized words or phrases into a single
2984 Here is an example of what not to do:
2987 printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
2990 If you apply gettext to all strings, like this,
2993 printf (gettext ("%s is full"),
2994 capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
2998 the translator will hardly know that "disk" and "floppy disk" are meant to
2999 be substituted in the other string. Worse, in some languages (like French)
3000 the construction will not work: the translation of the word "full" depends
3001 on the gender of the first part of the sentence; it happens to be not the
3002 same for "disk" as for "floppy disk".
3004 Complete sentences can be translated without problems:
3007 printf (capacity > 5000000 ? gettext ("disk is full")
3008 : gettext ("floppy disk is full"));
3011 A similar problem appears at the level of sentence structure with this
3015 printf ("# Implicit rule search has%s been done.\n",
3016 f->tried_implicit ? "" : " not");
3020 Adding @code{gettext} calls to this code cannot give correct results for
3021 all languages, because negation in some languages requires adding words
3022 at more than one place in the sentence. By contrast, adding
3023 @code{gettext} calls does the job straightforwardly if the code starts
3027 printf (f->tried_implicit
3028 ? "# Implicit rule search has been done.\n",
3029 : "# Implicit rule search has not been done.\n");
3032 Another example is this one:
3035 printf ("%d file%s processed", nfiles,
3036 nfiles != 1 ? "s" : "");
3040 The problem with this example is that it assumes that plurals are made
3041 by adding `s'. If you apply gettext to the format string, like this,
3044 printf (gettext ("%d file%s processed"), nfiles,
3045 nfiles != 1 ? "s" : "");
3049 the message can use different words, but it will still be forced to use
3050 `s' for the plural. Here is a better way, with gettext being applied to
3051 the two strings independently:
3054 printf ((nfiles != 1 ? gettext ("%d files processed")
3055 : gettext ("%d file processed")),
3060 But this still doesn't work for languages like Polish, which has three
3061 plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ...
3062 and one for the rest. The GNU @code{ngettext} function solves this problem:
3065 printf (ngettext ("%d files processed", "%d file processed", nfiles),
3071 @section Character Set
3072 @cindex character set
3074 @cindex ASCII characters
3075 @cindex non-ASCII characters
3077 Sticking to the ASCII character set (plain text, 7-bit characters) is
3078 preferred in GNU source code comments, text documents, and other
3079 contexts, unless there is good reason to do something else because of
3080 the application domain. For example, if source code deals with the
3081 French Revolutionary calendar, it is OK if its literal strings contain
3082 accented characters in month names like ``Flor@'eal''. Also, it is OK
3083 to use non-ASCII characters to represent proper names of contributors in
3084 change logs (@pxref{Change Logs}).
3086 If you need to use non-ASCII characters, you should normally stick with
3087 one encoding, as one cannot in general mix encodings reliably.
3090 @node Quote Characters
3091 @section Quote Characters
3092 @cindex quote characters
3093 @cindex locale-specific quote characters
3095 @cindex grave accent
3097 In the C locale, GNU programs should stick to plain ASCII for quotation
3098 characters in messages to users: preferably 0x60 (@samp{`}) for left
3099 quotes and 0x27 (@samp{'}) for right quotes. It is ok, but not
3100 required, to use locale-specific quotes in other locales.
3102 The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
3103 @code{quotearg} modules provide a reasonably straightforward way to
3104 support locale-specific quote characters, as well as taking care of
3105 other issues, such as quoting a filename that itself contains a quote
3106 character. See the Gnulib documentation for usage details.
3108 In any case, the documentation for your program should clearly specify
3109 how it does quoting, if different than the preferred method of @samp{`}
3110 and @samp{'}. This is especially important if the output of your
3111 program is ever likely to be parsed by another program.
3113 Quotation characters are a difficult area in the computing world at
3114 this time: there are no true left or right quote characters in Latin1;
3115 the @samp{`} character we use was standardized there as a grave
3116 accent. Moreover, Latin1 is still not universally usable.
3118 Unicode contains the unambiguous quote characters required, and its
3119 common encoding UTF-8 is upward compatible with Latin1. However,
3120 Unicode and UTF-8 are not universally well-supported, either.
3122 This may change over the next few years, and then we will revisit
3130 Don't assume that @code{mmap} either works on all files or fails
3131 for all files. It may work on some files and fail on others.
3133 The proper way to use @code{mmap} is to try it on the specific file for
3134 which you want to use it---and if @code{mmap} doesn't work, fall back on
3135 doing the job in another way using @code{read} and @code{write}.
3137 The reason this precaution is needed is that the GNU kernel (the HURD)
3138 provides a user-extensible file system, in which there can be many
3139 different kinds of ``ordinary files.'' Many of them support
3140 @code{mmap}, but some do not. It is important to make programs handle
3141 all these kinds of files.
3144 @chapter Documenting Programs
3145 @cindex documentation
3147 A GNU program should ideally come with full free documentation, adequate
3148 for both reference and tutorial purposes. If the package can be
3149 programmed or extended, the documentation should cover programming or
3150 extending it, as well as just using it.
3153 * GNU Manuals:: Writing proper manuals.
3154 * Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
3155 * Manual Structure Details:: Specific structure conventions.
3156 * License for Manuals:: Writing the distribution terms for a manual.
3157 * Manual Credits:: Giving credit to documentation contributors.
3158 * Printed Manuals:: Mentioning the printed manual.
3159 * NEWS File:: NEWS files supplement manuals.
3160 * Change Logs:: Recording Changes
3161 * Man Pages:: Man pages are secondary.
3162 * Reading other Manuals:: How far you can go in learning
3167 @section GNU Manuals
3169 The preferred document format for the GNU system is the Texinfo
3170 formatting language. Every GNU package should (ideally) have
3171 documentation in Texinfo both for reference and for learners. Texinfo
3172 makes it possible to produce a good quality formatted book, using
3173 @TeX{}, and to generate an Info file. It is also possible to generate
3174 HTML output from Texinfo source. See the Texinfo manual, either the
3175 hardcopy, or the on-line version available through @code{info} or the
3176 Emacs Info subsystem (@kbd{C-h i}).
3178 Nowadays some other formats such as Docbook and Sgmltexi can be
3179 converted automatically into Texinfo. It is ok to produce the Texinfo
3180 documentation by conversion this way, as long as it gives good results.
3182 Make sure your manual is clear to a reader who knows nothing about the
3183 topic and reads it straight through. This means covering basic topics
3184 at the beginning, and advanced topics only later. This also means
3185 defining every specialized term when it is first used.
3187 Programmers tend to carry over the structure of the program as the
3188 structure for its documentation. But this structure is not
3189 necessarily good for explaining how to use the program; it may be
3190 irrelevant and confusing for a user.
3192 Instead, the right way to structure documentation is according to the
3193 concepts and questions that a user will have in mind when reading it.
3194 This principle applies at every level, from the lowest (ordering
3195 sentences in a paragraph) to the highest (ordering of chapter topics
3196 within the manual). Sometimes this structure of ideas matches the
3197 structure of the implementation of the software being documented---but
3198 often they are different. An important part of learning to write good
3199 documentation is to learn to notice when you have unthinkingly
3200 structured the documentation like the implementation, stop yourself,
3201 and look for better alternatives.
3203 For example, each program in the GNU system probably ought to be
3204 documented in one manual; but this does not mean each program should
3205 have its own manual. That would be following the structure of the
3206 implementation, rather than the structure that helps the user
3209 Instead, each manual should cover a coherent @emph{topic}. For example,
3210 instead of a manual for @code{diff} and a manual for @code{diff3}, we
3211 have one manual for ``comparison of files'' which covers both of those
3212 programs, as well as @code{cmp}. By documenting these programs
3213 together, we can make the whole subject clearer.
3215 The manual which discusses a program should certainly document all of
3216 the program's command-line options and all of its commands. It should
3217 give examples of their use. But don't organize the manual as a list
3218 of features. Instead, organize it logically, by subtopics. Address
3219 the questions that a user will ask when thinking about the job that
3220 the program does. Don't just tell the reader what each feature can
3221 do---say what jobs it is good for, and show how to use it for those
3222 jobs. Explain what is recommended usage, and what kinds of usage
3225 In general, a GNU manual should serve both as tutorial and reference.
3226 It should be set up for convenient access to each topic through Info,
3227 and for reading straight through (appendixes aside). A GNU manual
3228 should give a good introduction to a beginner reading through from the
3229 start, and should also provide all the details that hackers want.
3230 The Bison manual is a good example of this---please take a look at it
3231 to see what we mean.
3233 That is not as hard as it first sounds. Arrange each chapter as a
3234 logical breakdown of its topic, but order the sections, and write their
3235 text, so that reading the chapter straight through makes sense. Do
3236 likewise when structuring the book into chapters, and when structuring a
3237 section into paragraphs. The watchword is, @emph{at each point, address
3238 the most fundamental and important issue raised by the preceding text.}
3240 If necessary, add extra chapters at the beginning of the manual which
3241 are purely tutorial and cover the basics of the subject. These provide
3242 the framework for a beginner to understand the rest of the manual. The
3243 Bison manual provides a good example of how to do this.
3245 To serve as a reference, a manual should have an Index that list all the
3246 functions, variables, options, and important concepts that are part of
3247 the program. One combined Index should do for a short manual, but
3248 sometimes for a complex package it is better to use multiple indices.
3249 The Texinfo manual includes advice on preparing good index entries, see
3250 @ref{Index Entries, , Making Index Entries, texinfo, GNU Texinfo}, and
3251 see @ref{Indexing Commands, , Defining the Entries of an
3252 Index, texinfo, GNU Texinfo}.
3254 Don't use Unix man pages as a model for how to write GNU documentation;
3255 most of them are terse, badly structured, and give inadequate
3256 explanation of the underlying concepts. (There are, of course, some
3257 exceptions.) Also, Unix man pages use a particular format which is
3258 different from what we use in GNU manuals.
3260 Please include an email address in the manual for where to report
3261 bugs @emph{in the text of the manual}.
3263 Please do not use the term ``pathname'' that is used in Unix
3264 documentation; use ``file name'' (two words) instead. We use the term
3265 ``path'' only for search paths, which are lists of directory names.
3267 Please do not use the term ``illegal'' to refer to erroneous input to
3268 a computer program. Please use ``invalid'' for this, and reserve the
3269 term ``illegal'' for activities prohibited by law.
3271 Please do not write @samp{()} after a function name just to indicate
3272 it is a function. @code{foo ()} is not a function, it is a function
3273 call with no arguments.
3275 @node Doc Strings and Manuals
3276 @section Doc Strings and Manuals
3278 Some programming systems, such as Emacs, provide a documentation string
3279 for each function, command or variable. You may be tempted to write a
3280 reference manual by compiling the documentation strings and writing a
3281 little additional text to go around them---but you must not do it. That
3282 approach is a fundamental mistake. The text of well-written
3283 documentation strings will be entirely wrong for a manual.
3285 A documentation string needs to stand alone---when it appears on the
3286 screen, there will be no other text to introduce or explain it.
3287 Meanwhile, it can be rather informal in style.
3289 The text describing a function or variable in a manual must not stand
3290 alone; it appears in the context of a section or subsection. Other text
3291 at the beginning of the section should explain some of the concepts, and
3292 should often make some general points that apply to several functions or
3293 variables. The previous descriptions of functions and variables in the
3294 section will also have given information about the topic. A description
3295 written to stand alone would repeat some of that information; this
3296 redundancy looks bad. Meanwhile, the informality that is acceptable in
3297 a documentation string is totally unacceptable in a manual.
3299 The only good way to use documentation strings in writing a good manual
3300 is to use them as a source of information for writing good text.
3302 @node Manual Structure Details
3303 @section Manual Structure Details
3304 @cindex manual structure
3306 The title page of the manual should state the version of the programs or
3307 packages documented in the manual. The Top node of the manual should
3308 also contain this information. If the manual is changing more
3309 frequently than or independent of the program, also state a version
3310 number for the manual in both of these places.
3312 Each program documented in the manual should have a node named
3313 @samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
3314 node (together with its subnodes, if any) should describe the program's
3315 command line arguments and how to run it (the sort of information people
3316 would look for in a man page). Start with an @samp{@@example}
3317 containing a template for all the options and arguments that the program
3320 Alternatively, put a menu item in some menu whose item name fits one of
3321 the above patterns. This identifies the node which that item points to
3322 as the node for this purpose, regardless of the node's actual name.
3324 The @samp{--usage} feature of the Info reader looks for such a node
3325 or menu item in order to find the relevant text, so it is essential
3326 for every Texinfo file to have one.
3328 If one manual describes several programs, it should have such a node for
3329 each program described in the manual.
3331 @node License for Manuals
3332 @section License for Manuals
3333 @cindex license for manuals
3335 Please use the GNU Free Documentation License for all GNU manuals that
3336 are more than a few pages long. Likewise for a collection of short
3337 documents---you only need one copy of the GNU FDL for the whole
3338 collection. For a single short document, you can use a very permissive
3339 non-copyleft license, to avoid taking up space with a long license.
3341 See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
3342 of how to employ the GFDL.
3344 Note that it is not obligatory to include a copy of the GNU GPL or GNU
3345 LGPL in a manual whose license is neither the GPL nor the LGPL. It can
3346 be a good idea to include the program's license in a large manual; in a
3347 short manual, whose size would be increased considerably by including
3348 the program's license, it is probably better not to include it.
3350 @node Manual Credits
3351 @section Manual Credits
3352 @cindex credits for manuals
3354 Please credit the principal human writers of the manual as the authors,
3355 on the title page of the manual. If a company sponsored the work, thank
3356 the company in a suitable place in the manual, but do not cite the
3357 company as an author.
3359 @node Printed Manuals
3360 @section Printed Manuals
3362 The FSF publishes some GNU manuals in printed form. To encourage sales
3363 of these manuals, the on-line versions of the manual should mention at
3364 the very start that the printed manual is available and should point at
3365 information for getting it---for instance, with a link to the page
3366 @url{http://www.gnu.org/order/order.html}. This should not be included
3367 in the printed manual, though, because there it is redundant.
3369 It is also useful to explain in the on-line forms of the manual how the
3370 user can print out the manual from the sources.
3373 @section The NEWS File
3374 @cindex @file{NEWS} file
3376 In addition to its manual, the package should have a file named
3377 @file{NEWS} which contains a list of user-visible changes worth
3378 mentioning. In each new release, add items to the front of the file and
3379 identify the version they pertain to. Don't discard old items; leave
3380 them in the file after the newer items. This way, a user upgrading from
3381 any previous version can see what is new.
3383 If the @file{NEWS} file gets very long, move some of the older items
3384 into a file named @file{ONEWS} and put a note at the end referring the
3388 @section Change Logs
3391 Keep a change log to describe all the changes made to program source
3392 files. The purpose of this is so that people investigating bugs in the
3393 future will know about the changes that might have introduced the bug.
3394 Often a new bug can be found by looking at what was recently changed.
3395 More importantly, change logs can help you eliminate conceptual
3396 inconsistencies between different parts of a program, by giving you a
3397 history of how the conflicting concepts arose and who they came from.
3400 * Change Log Concepts::
3401 * Style of Change Logs::
3403 * Conditional Changes::
3404 * Indicating the Part Changed::
3407 @node Change Log Concepts
3408 @subsection Change Log Concepts
3410 You can think of the change log as a conceptual ``undo list'' which
3411 explains how earlier versions were different from the current version.
3412 People can see the current version; they don't need the change log
3413 to tell them what is in it. What they want from a change log is a
3414 clear explanation of how the earlier version differed.
3416 The change log file is normally called @file{ChangeLog} and covers an
3417 entire directory. Each directory can have its own change log, or a
3418 directory can use the change log of its parent directory--it's up to
3421 Another alternative is to record change log information with a version
3422 control system such as RCS or CVS. This can be converted automatically
3423 to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
3424 @kbd{C-x v a} (@code{vc-update-change-log}) does the job.
3426 There's no need to describe the full purpose of the changes or how they
3427 work together. If you think that a change calls for explanation, you're
3428 probably right. Please do explain it---but please put the explanation
3429 in comments in the code, where people will see it whenever they see the
3430 code. For example, ``New function'' is enough for the change log when
3431 you add a function, because there should be a comment before the
3432 function definition to explain what it does.
3434 In the past, we recommended not mentioning changes in non-software
3435 files (manuals, help files, etc.) in change logs. However, we've been
3436 advised that it is a good idea to include them, for the sake of
3439 However, sometimes it is useful to write one line to describe the
3440 overall purpose of a batch of changes.
3442 The easiest way to add an entry to @file{ChangeLog} is with the Emacs
3443 command @kbd{M-x add-change-log-entry}. An entry should have an
3444 asterisk, the name of the changed file, and then in parentheses the name
3445 of the changed functions, variables or whatever, followed by a colon.
3446 Then describe the changes you made to that function or variable.
3448 @node Style of Change Logs
3449 @subsection Style of Change Logs
3450 @cindex change logs, style
3452 Here are some simple examples of change log entries, starting with the
3453 header line that says who made the change and when it was installed,
3454 followed by descriptions of specific changes. (These examples are
3455 drawn from Emacs and GCC.)
3458 1998-08-17 Richard Stallman <rms@@gnu.org>
3460 * register.el (insert-register): Return nil.
3461 (jump-to-register): Likewise.
3463 * sort.el (sort-subr): Return nil.
3465 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3466 Restart the tex shell if process is gone or stopped.
3467 (tex-shell-running): New function.
3469 * expr.c (store_one_arg): Round size up for move_block_to_reg.
3470 (expand_call): Round up when emitting USE insns.
3471 * stmt.c (assign_parms): Round size up for move_block_from_reg.
3474 It's important to name the changed function or variable in full. Don't
3475 abbreviate function or variable names, and don't combine them.
3476 Subsequent maintainers will often search for a function name to find all
3477 the change log entries that pertain to it; if you abbreviate the name,
3478 they won't find it when they search.
3480 For example, some people are tempted to abbreviate groups of function
3481 names by writing @samp{* register.el (@{insert,jump-to@}-register)};
3482 this is not a good idea, since searching for @code{jump-to-register} or
3483 @code{insert-register} would not find that entry.
3485 Separate unrelated change log entries with blank lines. When two
3486 entries represent parts of the same change, so that they work together,
3487 then don't put blank lines between them. Then you can omit the file
3488 name and the asterisk when successive entries are in the same file.
3490 Break long lists of function names by closing continued lines with
3491 @samp{)}, rather than @samp{,}, and opening the continuation with
3492 @samp{(} as in this example:
3495 * keyboard.c (menu_bar_items, tool_bar_items)
3496 (Fexecute_extended_command): Deal with `keymap' property.
3499 When you install someone else's changes, put the contributor's name in
3500 the change log entry rather than in the text of the entry. In other
3504 2002-07-14 John Doe <jdoe@@gnu.org>
3506 * sewing.c: Make it sew.
3513 2002-07-14 Usual Maintainer <usual@@gnu.org>
3515 * sewing.c: Make it sew. Patch by jdoe@@gnu.org.
3518 As for the date, that should be the date you applied the change.
3520 @node Simple Changes
3521 @subsection Simple Changes
3523 Certain simple kinds of changes don't need much detail in the change
3526 When you change the calling sequence of a function in a simple fashion,
3527 and you change all the callers of the function to use the new calling
3528 sequence, there is no need to make individual entries for all the
3529 callers that you changed. Just write in the entry for the function
3530 being called, ``All callers changed''---like this:
3533 * keyboard.c (Fcommand_execute): New arg SPECIAL.
3534 All callers changed.
3537 When you change just comments or doc strings, it is enough to write an
3538 entry for the file, without mentioning the functions. Just ``Doc
3539 fixes'' is enough for the change log.
3541 There's no technical need to make change log entries for documentation
3542 files. This is because documentation is not susceptible to bugs that
3543 are hard to fix. Documentation does not consist of parts that must
3544 interact in a precisely engineered fashion. To correct an error, you
3545 need not know the history of the erroneous passage; it is enough to
3546 compare what the documentation says with the way the program actually
3549 However, you should keep change logs for documentation files when the
3550 project gets copyright assignments from its contributors, so as to
3551 make the records of authorship more accurate.
3553 @node Conditional Changes
3554 @subsection Conditional Changes
3555 @cindex conditional changes, and change logs
3556 @cindex change logs, conditional changes
3558 C programs often contain compile-time @code{#if} conditionals. Many
3559 changes are conditional; sometimes you add a new definition which is
3560 entirely contained in a conditional. It is very useful to indicate in
3561 the change log the conditions for which the change applies.
3563 Our convention for indicating conditional changes is to use square
3564 brackets around the name of the condition.
3566 Here is a simple example, describing a change which is conditional but
3567 does not have a function or entity name associated with it:
3570 * xterm.c [SOLARIS2]: Include string.h.
3573 Here is an entry describing a new definition which is entirely
3574 conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
3575 used only when @code{HAVE_X_WINDOWS} is defined:
3578 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3581 Here is an entry for a change within the function @code{init_display},
3582 whose definition as a whole is unconditional, but the changes themselves
3583 are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
3586 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3589 Here is an entry for a change that takes affect only when
3590 a certain macro is @emph{not} defined:
3593 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3596 @node Indicating the Part Changed
3597 @subsection Indicating the Part Changed
3599 Indicate the part of a function which changed by using angle brackets
3600 enclosing an indication of what the changed part does. Here is an entry
3601 for a change in the part of the function @code{sh-while-getopts} that
3602 deals with @code{sh} commands:
3605 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3606 user-specified option string is empty.
3614 In the GNU project, man pages are secondary. It is not necessary or
3615 expected for every GNU program to have a man page, but some of them do.
3616 It's your choice whether to include a man page in your program.
3618 When you make this decision, consider that supporting a man page
3619 requires continual effort each time the program is changed. The time
3620 you spend on the man page is time taken away from more useful work.
3622 For a simple program which changes little, updating the man page may be
3623 a small job. Then there is little reason not to include a man page, if
3626 For a large program that changes a great deal, updating a man page may
3627 be a substantial burden. If a user offers to donate a man page, you may
3628 find this gift costly to accept. It may be better to refuse the man
3629 page unless the same person agrees to take full responsibility for
3630 maintaining it---so that you can wash your hands of it entirely. If
3631 this volunteer later ceases to do the job, then don't feel obliged to
3632 pick it up yourself; it may be better to withdraw the man page from the
3633 distribution until someone else agrees to update it.
3635 When a program changes only a little, you may feel that the
3636 discrepancies are small enough that the man page remains useful without
3637 updating. If so, put a prominent note near the beginning of the man
3638 page explaining that you don't maintain it and that the Texinfo manual
3639 is more authoritative. The note should say how to access the Texinfo
3642 Be sure that man pages include a copyright statement and free
3643 license. The simple all-permissive license is appropriate for simple
3647 Copying and distribution of this file, with or without modification,
3648 are permitted in any medium without royalty provided the copyright
3649 notice and this notice are preserved.
3652 For long man pages, with enough explanation and documentation that
3653 they can be considered true manuals, use the GFDL (@pxref{License for
3656 Finally, the GNU help2man program
3657 (@uref{http://www.gnu.org/software/help2man/}) is one way to automate
3658 generation of a man page, in this case from @option{--help} output.
3659 This is sufficient in many cases.
3661 @node Reading other Manuals
3662 @section Reading other Manuals
3664 There may be non-free books or documentation files that describe the
3665 program you are documenting.
3667 It is ok to use these documents for reference, just as the author of a
3668 new algebra textbook can read other books on algebra. A large portion
3669 of any non-fiction book consists of facts, in this case facts about how
3670 a certain program works, and these facts are necessarily the same for
3671 everyone who writes about the subject. But be careful not to copy your
3672 outline structure, wording, tables or examples from preexisting non-free
3673 documentation. Copying from free documentation may be ok; please check
3674 with the FSF about the individual case.
3676 @node Managing Releases
3677 @chapter The Release Process
3680 Making a release is more than just bundling up your source files in a
3681 tar file and putting it up for FTP. You should set up your software so
3682 that it can be configured to run on a variety of systems. Your Makefile
3683 should conform to the GNU standards described below, and your directory
3684 layout should also conform to the standards discussed below. Doing so
3685 makes it easy to include your package into the larger framework of
3689 * Configuration:: How Configuration Should Work
3690 * Makefile Conventions:: Makefile Conventions
3691 * Releases:: Making Releases
3695 @section How Configuration Should Work
3696 @cindex program configuration
3699 Each GNU distribution should come with a shell script named
3700 @code{configure}. This script is given arguments which describe the
3701 kind of machine and system you want to compile the program for.
3703 The @code{configure} script must record the configuration options so
3704 that they affect compilation.
3706 One way to do this is to make a link from a standard name such as
3707 @file{config.h} to the proper configuration file for the chosen system.
3708 If you use this technique, the distribution should @emph{not} contain a
3709 file named @file{config.h}. This is so that people won't be able to
3710 build the program without configuring it first.
3712 Another thing that @code{configure} can do is to edit the Makefile. If
3713 you do this, the distribution should @emph{not} contain a file named
3714 @file{Makefile}. Instead, it should include a file @file{Makefile.in} which
3715 contains the input used for editing. Once again, this is so that people
3716 won't be able to build the program without configuring it first.
3718 If @code{configure} does write the @file{Makefile}, then @file{Makefile}
3719 should have a target named @file{Makefile} which causes @code{configure}
3720 to be rerun, setting up the same configuration that was set up last
3721 time. The files that @code{configure} reads should be listed as
3722 dependencies of @file{Makefile}.
3724 All the files which are output from the @code{configure} script should
3725 have comments at the beginning explaining that they were generated
3726 automatically using @code{configure}. This is so that users won't think
3727 of trying to edit them by hand.
3729 The @code{configure} script should write a file named @file{config.status}
3730 which describes which configuration options were specified when the
3731 program was last configured. This file should be a shell script which,
3732 if run, will recreate the same configuration.
3734 The @code{configure} script should accept an option of the form
3735 @samp{--srcdir=@var{dirname}} to specify the directory where sources are found
3736 (if it is not the current directory). This makes it possible to build
3737 the program in a separate directory, so that the actual source directory
3740 If the user does not specify @samp{--srcdir}, then @code{configure} should
3741 check both @file{.} and @file{..} to see if it can find the sources. If
3742 it finds the sources in one of these places, it should use them from
3743 there. Otherwise, it should report that it cannot find the sources, and
3744 should exit with nonzero status.
3746 Usually the easy way to support @samp{--srcdir} is by editing a
3747 definition of @code{VPATH} into the Makefile. Some rules may need to
3748 refer explicitly to the specified source directory. To make this
3749 possible, @code{configure} can add to the Makefile a variable named
3750 @code{srcdir} whose value is precisely the specified directory.
3752 The @code{configure} script should also take an argument which specifies the
3753 type of system to build the program for. This argument should look like
3757 @var{cpu}-@var{company}-@var{system}
3760 For example, an Athlon-based GNU/Linux system might be
3761 @samp{i686-pc-linux-gnu}.
3763 The @code{configure} script needs to be able to decode all plausible
3764 alternatives for how to describe a machine. Thus,
3765 @samp{athlon-pc-gnu/linux} would be a valid alias. There is a shell
3767 @uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.sub,
3768 @file{config.sub}} that you can use as a subroutine to validate system
3769 types and canonicalize aliases.
3771 The @code{configure} script should also take the option
3772 @option{--build=@var{buildtype}}, which should be equivalent to a
3773 plain @var{buildtype} argument. For example, @samp{configure
3774 --build=i686-pc-linux-gnu} is equivalent to @samp{configure
3775 i686-pc-linux-gnu}. When the build type is not specified by an option
3776 or argument, the @code{configure} script should normally guess it using
3778 @uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.guess,
3779 @file{config.guess}}.
3781 @cindex optional features, configure-time
3782 Other options are permitted to specify in more detail the software
3783 or hardware present on the machine, to include or exclude optional parts
3784 of the package, or to adjust the name of some tools or arguments to them:
3787 @item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
3788 Configure the package to build and install an optional user-level
3789 facility called @var{feature}. This allows users to choose which
3790 optional features to include. Giving an optional @var{parameter} of
3791 @samp{no} should omit @var{feature}, if it is built by default.
3793 No @samp{--enable} option should @strong{ever} cause one feature to
3794 replace another. No @samp{--enable} option should ever substitute one
3795 useful behavior for another useful behavior. The only proper use for
3796 @samp{--enable} is for questions of whether to build part of the program
3799 @item --with-@var{package}
3800 @c @r{[}=@var{parameter}@r{]}
3801 The package @var{package} will be installed, so configure this package
3802 to work with @var{package}.
3804 @c Giving an optional @var{parameter} of
3805 @c @samp{no} should omit @var{package}, if it is used by default.
3807 Possible values of @var{package} include
3808 @samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
3814 Do not use a @samp{--with} option to specify the file name to use to
3815 find certain files. That is outside the scope of what @samp{--with}
3818 @item @var{variable}=@var{value}
3819 Set the value of the variable @var{variable} to @var{value}. This is
3820 used to override the default values of commands or arguments in the
3821 build process. For example, the user could issue @samp{configure
3822 CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without
3823 the default optimization.
3825 Specifying variables as arguments to @code{configure}, like this:
3829 is preferable to setting them in environment variables:
3833 as it helps to recreate the same configuration later with
3834 @file{config.status}.
3837 All @code{configure} scripts should accept all of the ``detail''
3838 options and the variable settings, whether or not they make any
3839 difference to the particular package at hand. In particular, they
3840 should accept any option that starts with @samp{--with-} or
3841 @samp{--enable-}. This is so users will be able to configure an
3842 entire GNU source tree at once with a single set of options.
3844 You will note that the categories @samp{--with-} and @samp{--enable-}
3845 are narrow: they @strong{do not} provide a place for any sort of option
3846 you might think of. That is deliberate. We want to limit the possible
3847 configuration options in GNU software. We do not want GNU programs to
3848 have idiosyncratic configuration options.
3850 Packages that perform part of the compilation process may support
3851 cross-compilation. In such a case, the host and target machines for the
3852 program may be different.
3854 The @code{configure} script should normally treat the specified type of
3855 system as both the host and the target, thus producing a program which
3856 works for the same type of machine that it runs on.
3858 To compile a program to run on a host type that differs from the build
3859 type, use the configure option @option{--host=@var{hosttype}}, where
3860 @var{hosttype} uses the same syntax as @var{buildtype}. The host type
3861 normally defaults to the build type.
3863 To configure a cross-compiler, cross-assembler, or what have you, you
3864 should specify a target different from the host, using the configure
3865 option @samp{--target=@var{targettype}}. The syntax for
3866 @var{targettype} is the same as for the host type. So the command would
3870 ./configure --host=@var{hosttype} --target=@var{targettype}
3873 The target type normally defaults to the host type.
3874 Programs for which cross-operation is not meaningful need not accept the
3875 @samp{--target} option, because configuring an entire operating system for
3876 cross-operation is not a meaningful operation.
3878 Some programs have ways of configuring themselves automatically. If
3879 your program is set up to do this, your @code{configure} script can simply
3880 ignore most of its arguments.
3882 @comment The makefile standards are in a separate file that is also
3883 @comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
3884 @comment For this document, turn chapters into sections, etc.
3886 @include make-stds.texi
3890 @section Making Releases
3893 You should identify each release with a pair of version numbers, a
3894 major version and a minor. We have no objection to using more than
3895 two numbers, but it is very unlikely that you really need them.
3897 Package the distribution of @code{Foo version 69.96} up in a gzipped tar
3898 file with the name @file{foo-69.96.tar.gz}. It should unpack into a
3899 subdirectory named @file{foo-69.96}.
3901 Building and installing the program should never modify any of the files
3902 contained in the distribution. This means that all the files that form
3903 part of the program in any way must be classified into @dfn{source
3904 files} and @dfn{non-source files}. Source files are written by humans
3905 and never changed automatically; non-source files are produced from
3906 source files by programs under the control of the Makefile.
3908 @cindex @file{README} file
3909 The distribution should contain a file named @file{README} which gives
3910 the name of the package, and a general description of what it does. It
3911 is also good to explain the purpose of each of the first-level
3912 subdirectories in the package, if there are any. The @file{README} file
3913 should either state the version number of the package, or refer to where
3914 in the package it can be found.
3916 The @file{README} file should refer to the file @file{INSTALL}, which
3917 should contain an explanation of the installation procedure.
3919 The @file{README} file should also refer to the file which contains the
3920 copying conditions. The GNU GPL, if used, should be in a file called
3921 @file{COPYING}. If the GNU LGPL is used, it should be in a file called
3924 Naturally, all the source files must be in the distribution. It is okay
3925 to include non-source files in the distribution, provided they are
3926 up-to-date and machine-independent, so that building the distribution
3927 normally will never modify them. We commonly include non-source files
3928 produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
3929 unnecessary dependencies between our distributions, so that users can
3930 install whichever packages they want to install.
3932 Non-source files that might actually be modified by building and
3933 installing the program should @strong{never} be included in the
3934 distribution. So if you do distribute non-source files, always make
3935 sure they are up to date when you make a new distribution.
3937 Make sure that the directory into which the distribution unpacks (as
3938 well as any subdirectories) are all world-writable (octal mode 777).
3939 This is so that old versions of @code{tar} which preserve the
3940 ownership and permissions of the files from the tar archive will be
3941 able to extract all the files even if the user is unprivileged.
3943 Make sure that all the files in the distribution are world-readable.
3945 Don't include any symbolic links in the distribution itself. If the tar
3946 file contains symbolic links, then people cannot even unpack it on
3947 systems that don't support symbolic links. Also, don't use multiple
3948 names for one file in different directories, because certain file
3949 systems cannot handle this and that prevents unpacking the
3952 Try to make sure that all the file names will be unique on MS-DOS. A
3953 name on MS-DOS consists of up to 8 characters, optionally followed by a
3954 period and up to three characters. MS-DOS will truncate extra
3955 characters both before and after the period. Thus,
3956 @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
3957 are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
3960 @cindex @file{texinfo.tex}, in a distribution
3961 Include in your distribution a copy of the @file{texinfo.tex} you used
3962 to test print any @file{*.texinfo} or @file{*.texi} files.
3964 Likewise, if your program uses small GNU software packages like regex,
3965 getopt, obstack, or termcap, include them in the distribution file.
3966 Leaving them out would make the distribution file a little smaller at
3967 the expense of possible inconvenience to a user who doesn't know what
3971 @chapter References to Non-Free Software and Documentation
3972 @cindex references to non-free material
3974 A GNU program should not recommend use of any non-free program. We
3975 can't stop some people from writing proprietary programs, or stop
3976 other people from using them, but we can and should refuse to
3977 advertise them to new potential customers. Proprietary software is a
3978 social and ethical problem, and the point of GNU is to solve that
3981 The GNU definition of free software is found on the GNU web site at
3982 @url{http://www.gnu.org/philosophy/free-sw.html}, and the definition
3983 of free documentation is found at
3984 @url{http://www.gnu.org/philosophy/free-doc.html}. A list of
3985 important licenses and whether they qualify as free is in
3986 @url{http://www.gnu.org/@/licenses/@/license-list.html}. The terms
3987 ``free'' and ``non-free'', used in this document, refer to that
3988 definition. If it is not clear whether a license qualifies as free
3989 under this definition, please ask the GNU Project by writing to
3990 @email{licensing@@gnu.org}. We will answer, and if the license is an
3991 important one, we will add it to the list.
3993 When a non-free program or system is well known, you can mention it in
3994 passing---that is harmless, since users who might want to use it
3995 probably already know about it. For instance, it is fine to explain
3996 how to build your package on top of some widely used non-free
3997 operating system, or how to use it together with some widely used
4000 However, you should give only the necessary information to help those
4001 who already use the non-free program to use your program with
4002 it---don't give, or refer to, any further information about the
4003 proprietary program, and don't imply that the proprietary program
4004 enhances your program, or that its existence is in any way a good
4005 thing. The goal should be that people already using the proprietary
4006 program will get the advice they need about how to use your free
4007 program with it, while people who don't already use the proprietary
4008 program will not see anything to lead them to take an interest in it.
4010 If a non-free program or system is obscure in your program's domain,
4011 your program should not mention or support it at all, since doing so
4012 would tend to popularize the non-free program more than it popularizes
4013 your program. (You cannot hope to find many additional users among
4014 the users of Foobar if the users of Foobar are few.)
4016 Sometimes a program is free software in itself but depends on a
4017 non-free platform in order to run. For instance, many Java programs
4018 depend on the parts of Sun's Java implementation which are not yet
4019 free software, and won't run on the GNU Java Compiler (which does not
4020 yet have all the features) or won't run with the GNU Java libraries.
4021 We hope this particular problem will be gone in a few months, when Sun
4022 makes the standard Java libraries free software, but of course the
4023 general principle remains: you should not recommend programs that
4024 depend on non-free software to run.
4026 Some free programs encourage the use of non-free software. A typical
4027 example is @command{mplayer}. It is free software in itself, and the
4028 free code can handle some kinds of files. However, @command{mplayer}
4029 recommends use of non-free codecs for other kinds of files, and users
4030 that install @command{mplayer} are very likely to install those codecs
4031 along with it. To recommend @command{mplayer} is, in effect, to
4032 recommend the non-free codecs. We must not do that, so we cannot
4033 recommend @command{mplayer} either.
4035 In general, you should also not recommend programs that themselves
4036 strongly recommend the use of non-free software.
4038 A GNU package should not refer the user to any non-free documentation
4039 for free software. Free documentation that can be included in free
4040 operating systems is essential for completing the GNU system, or any
4041 free operating system, so it is a major focus of the GNU Project; to
4042 recommend use of documentation that we are not allowed to use in GNU
4043 would weaken the impetus for the community to produce documentation
4044 that we can include. So GNU packages should never recommend non-free
4047 By contrast, it is ok to refer to journal articles and textbooks in
4048 the comments of a program for explanation of how it functions, even
4049 though they be non-free. This is because we don't include such things
4050 in the GNU system even if we are allowed to---they are outside the
4051 scope of an operating system project.
4053 Referring to a web site that describes or recommends a non-free
4054 program is in effect promoting that software, so please do not make
4055 links (or mention by name) web sites that contain such material. This
4056 policy is relevant particularly for the web pages for a GNU package.
4058 Following links from nearly any web site can lead to non-free
4059 software; this is an inescapable aspect of the nature of the web, and
4060 in itself is no objection to linking to a site. As long as the site
4061 does not itself recommend a non-free program, there is no need be
4062 concerned about the sites it links to for other reasons.
4064 Thus, for example, you should not make a link to AT&T's web site,
4065 because that recommends AT&T's non-free software packages; you should
4066 not make a link to a site that links to AT&T's site saying it is a
4067 place to get a non-free program; but if a site you want to link to
4068 refers to AT&T's web site in some other context (such as long-distance
4069 telephone service), that is not a problem.
4071 @node Copying This Manual
4072 @appendix Copying This Manual
4075 * GNU Free Documentation License:: License for copying this manual
4087 eval: (add-hook 'write-file-hooks 'time-stamp)
4088 time-stamp-start: "@set lastupdate "
4090 time-stamp-format: "%:b %:d, %:y"
4091 compile-command: "make just-standards"