OpenCores
URL https://opencores.org/ocsvn/open8_urisc/open8_urisc/trunk

Subversion Repositories open8_urisc

[/] [open8_urisc/] [trunk/] [gnu/] [binutils/] [etc/] [standards.texi] - Blame information for rev 84

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 19 khays
\input texinfo @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename standards.info
4
@settitle GNU Coding Standards
5
@c This date is automagically updated when you save this file:
6
@set lastupdate April 12, 2010
7
@c %**end of header
8
 
9
@dircategory GNU organization
10
@direntry
11
* Standards: (standards).       GNU coding standards.
12
@end direntry
13
 
14
@c @setchapternewpage odd
15
@setchapternewpage off
16
 
17
@c Put everything in one index (arbitrarily chosen to be the concept index).
18
@syncodeindex fn cp
19
@syncodeindex ky cp
20
@syncodeindex pg cp
21
@syncodeindex vr cp
22
 
23
@c This is used by a cross ref in make-stds.texi
24
@set CODESTD  1
25
 
26
@copying
27
The GNU coding standards, last updated @value{lastupdate}.
28
 
29
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
30
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
31
Foundation, Inc.
32
 
33
Permission is granted to copy, distribute and/or modify this document
34
under the terms of the GNU Free Documentation License, Version 1.3 or
35
any later version published by the Free Software Foundation; with no
36
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
37
Texts.  A copy of the license is included in the section entitled
38
``GNU Free Documentation License''.
39
@end copying
40
 
41
@titlepage
42
@title GNU Coding Standards
43
@author Richard Stallman, et al.
44
@author last updated @value{lastupdate}
45
@page
46
@vskip 0pt plus 1filll
47
@insertcopying
48
@end titlepage
49
 
50
@contents
51
 
52
@ifnottex
53
@node Top, Preface, (dir), (dir)
54
@top Version
55
 
56
@insertcopying
57
@end ifnottex
58
 
59
@menu
60
* Preface::                     About the GNU Coding Standards.
61
* Legal Issues::                Keeping free software free.
62
* Design Advice::               General program design.
63
* Program Behavior::            Program behavior for all programs
64
* Writing C::                   Making the best use of C.
65
* Documentation::               Documenting programs.
66
* Managing Releases::           The release process.
67
* References::                  Mentioning non-free software or documentation.
68
* GNU Free Documentation License::  Copying and sharing this manual.
69
* Index::
70
 
71
@end menu
72
 
73
@node Preface
74
@chapter About the GNU Coding Standards
75
 
76
The GNU Coding Standards were written by Richard Stallman and other GNU
77
Project volunteers.  Their purpose is to make the GNU system clean,
78
consistent, and easy to install.  This document can also be read as a
79
guide to writing portable, robust and reliable programs.  It focuses on
80
programs written in C, but many of the rules and principles are useful
81
even if you write in another programming language.  The rules often
82
state reasons for writing in a certain way.
83
 
84
@cindex where to obtain @code{standards.texi}
85
@cindex downloading this manual
86
If you did not obtain this file directly from the GNU project and
87
recently, please check for a newer version.  You can get the GNU
88
Coding Standards from the GNU web server in many
89
different formats, including the Texinfo source, PDF, HTML, DVI, plain
90
text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
91
 
92
If you are maintaining an official GNU package, in addition to this
93
document, please read and follow the GNU maintainer information
94
(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU
95
Software}).
96
 
97
@cindex @code{gnustandards-commit@@gnu.org} mailing list
98
If you want to receive diffs for every change to these GNU documents,
99
join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
100
interface at
101
@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
102
Archives are also available there.
103
 
104
@cindex @code{bug-standards@@gnu.org} email address
105
@cindex Savannah repository for gnustandards
106
@cindex gnustandards project repository
107
Please send corrections or suggestions for this document to
108
@email{bug-standards@@gnu.org}.  If you make a suggestion, please
109
include a suggested new wording for it, to help us consider the
110
suggestion efficiently.  We prefer a context diff to the Texinfo
111
source, but if that's difficult for you, you can make a context diff
112
for some other version of this document, or propose it in any way that
113
makes it clear.  The source repository for this document can be found
114
at @url{http://savannah.gnu.org/projects/gnustandards}.
115
 
116
These standards cover the minimum of what is important when writing a
117
GNU package.  Likely, the need for additional standards will come up.
118
Sometimes, you might suggest that such standards be added to this
119
document.  If you think your standards would be generally useful, please
120
do suggest them.
121
 
122
You should also set standards for your package on many questions not
123
addressed or not firmly specified here.  The most important point is to
124
be self-consistent---try to stick to the conventions you pick, and try
125
to document them as much as possible.  That way, your program will be
126
more maintainable by others.
127
 
128
The GNU Hello program serves as an example of how to follow the GNU
129
coding standards for a trivial program.
130
@uref{http://www.gnu.org/software/hello/hello.html}.
131
 
132
This release of the GNU Coding Standards was last updated
133
@value{lastupdate}.
134
 
135
 
136
@node Legal Issues
137
@chapter Keeping Free Software Free
138
@cindex legal aspects
139
 
140
This chapter discusses how you can make sure that GNU software
141
avoids legal difficulties, and other related issues.
142
 
143
@menu
144
* Reading Non-Free Code::       Referring to proprietary programs.
145
* Contributions::               Accepting contributions.
146
* Trademarks::                  How we deal with trademark issues.
147
@end menu
148
 
149
@node Reading Non-Free Code
150
@section Referring to Proprietary Programs
151
@cindex proprietary programs
152
@cindex avoiding proprietary code
153
 
154
Don't in any circumstances refer to Unix source code for or during
155
your work on GNU!  (Or to any other proprietary programs.)
156
 
157
If you have a vague recollection of the internals of a Unix program,
158
this does not absolutely mean you can't write an imitation of it, but
159
do try to organize the imitation internally along different lines,
160
because this is likely to make the details of the Unix version
161
irrelevant and dissimilar to your results.
162
 
163
For example, Unix utilities were generally optimized to minimize
164
memory use; if you go for speed instead, your program will be very
165
different.  You could keep the entire input file in memory and scan it
166
there instead of using stdio.  Use a smarter algorithm discovered more
167
recently than the Unix program.  Eliminate use of temporary files.  Do
168
it in one pass instead of two (we did this in the assembler).
169
 
170
Or, on the contrary, emphasize simplicity instead of speed.  For some
171
applications, the speed of today's computers makes simpler algorithms
172
adequate.
173
 
174
Or go for generality.  For example, Unix programs often have static
175
tables or fixed-size strings, which make for arbitrary limits; use
176
dynamic allocation instead.  Make sure your program handles NULs and
177
other funny characters in the input files.  Add a programming language
178
for extensibility and write part of the program in that language.
179
 
180
Or turn some parts of the program into independently usable libraries.
181
Or use a simple garbage collector instead of tracking precisely when
182
to free memory, or use a new GNU facility such as obstacks.
183
 
184
@node Contributions
185
@section Accepting Contributions
186
@cindex legal papers
187
@cindex accepting contributions
188
 
189
If the program you are working on is copyrighted by the Free Software
190
Foundation, then when someone else sends you a piece of code to add to
191
the program, we need legal papers to use it---just as we asked you to
192
sign papers initially.  @emph{Each} person who makes a nontrivial
193
contribution to a program must sign some sort of legal papers in order
194
for us to have clear title to the program; the main author alone is not
195
enough.
196
 
197
So, before adding in any contributions from other people, please tell
198
us, so we can arrange to get the papers.  Then wait until we tell you
199
that we have received the signed papers, before you actually use the
200
contribution.
201
 
202
This applies both before you release the program and afterward.  If
203
you receive diffs to fix a bug, and they make significant changes, we
204
need legal papers for that change.
205
 
206
This also applies to comments and documentation files.  For copyright
207
law, comments and code are just text.  Copyright applies to all kinds of
208
text, so we need legal papers for all kinds.
209
 
210
We know it is frustrating to ask for legal papers; it's frustrating for
211
us as well.  But if you don't wait, you are going out on a limb---for
212
example, what if the contributor's employer won't sign a disclaimer?
213
You might have to take that code out again!
214
 
215
You don't need papers for changes of a few lines here or there, since
216
they are not significant for copyright purposes.  Also, you don't need
217
papers if all you get from the suggestion is some ideas, not actual code
218
which you use.  For example, if someone sent you one implementation, but
219
you write a different implementation of the same idea, you don't need to
220
get papers.
221
 
222
The very worst thing is if you forget to tell us about the other
223
contributor.  We could be very embarrassed in court some day as a
224
result.
225
 
226
We have more detailed advice for maintainers of programs; if you have
227
reached the stage of actually maintaining a program for GNU (whether
228
released or not), please ask us for a copy.  It is also available
229
online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.
230
 
231
@node Trademarks
232
@section Trademarks
233
@cindex trademarks
234
 
235
Please do not include any trademark acknowledgements in GNU software
236
packages or documentation.
237
 
238
Trademark acknowledgements are the statements that such-and-such is a
239
trademark of so-and-so.  The GNU Project has no objection to the basic
240
idea of trademarks, but these acknowledgements feel like kowtowing,
241
and there is no legal requirement for them, so we don't use them.
242
 
243
What is legally required, as regards other people's trademarks, is to
244
avoid using them in ways which a reader might reasonably understand as
245
naming or labeling our own programs or activities.  For example, since
246
``Objective C'' is (or at least was) a trademark, we made sure to say
247
that we provide a ``compiler for the Objective C language'' rather
248
than an ``Objective C compiler''.  The latter would have been meant as
249
a shorter way of saying the former, but it does not explicitly state
250
the relationship, so it could be misinterpreted as using ``Objective
251
C'' as a label for the compiler rather than for the language.
252
 
253
Please don't use ``win'' as an abbreviation for Microsoft Windows in
254
GNU software or documentation.  In hacker terminology, calling
255
something a ``win'' is a form of praise.  If you wish to praise
256
Microsoft Windows when speaking on your own, by all means do so, but
257
not in GNU software.  Usually we write the name ``Windows'' in full,
258
but when brevity is very important (as in file names and sometimes
259
symbol names), we abbreviate it to ``w''.  For instance, the files and
260
functions in Emacs that deal with Windows start with @samp{w32}.
261
 
262
@node Design Advice
263
@chapter General Program Design
264
@cindex program design
265
 
266
This chapter discusses some of the issues you should take into
267
account when designing your program.
268
 
269
@c                         Standard or ANSI C
270
@c
271
@c In 1989 the American National Standards Institute (ANSI) standardized
272
@c C   as  standard  X3.159-1989.    In  December   of  that   year  the
273
@c International Standards Organization ISO  adopted the ANSI C standard
274
@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard
275
@c C. This version of C is known as either ANSI C or Standard C.
276
 
277
@c A major revision of the C Standard appeared in 1999.
278
 
279
@menu
280
* Source Language::             Which languages to use.
281
* Compatibility::               Compatibility with other implementations.
282
* Using Extensions::            Using non-standard features.
283
* Standard C::                  Using standard C features.
284
* Conditional Compilation::     Compiling code only if a conditional is true.
285
@end menu
286
 
287
@node Source Language
288
@section Which Languages to Use
289
@cindex programming languages
290
 
291
When you want to use a language that gets compiled and runs at high
292
speed, the best language to use is C.  Using another language is like
293
using a non-standard feature: it will cause trouble for users.  Even if
294
GCC supports the other language, users may find it inconvenient to have
295
to install the compiler for that other language in order to build your
296
program.  For example, if you write your program in C++, people will
297
have to install the GNU C++ compiler in order to compile your program.
298
 
299
C has one other advantage over C++ and other compiled languages: more
300
people know C, so more people will find it easy to read and modify the
301
program if it is written in C.
302
 
303
So in general it is much better to use C, rather than the
304
comparable alternatives.
305
 
306
But there are two exceptions to that conclusion:
307
 
308
@itemize @bullet
309
@item
310
It is no problem to use another language to write a tool specifically
311
intended for use with that language.  That is because the only people
312
who want to build the tool will be those who have installed the other
313
language anyway.
314
 
315
@item
316
If an application is of interest only to a narrow part of the community,
317
then the question of which language it is written in has less effect on
318
other people, so you may as well please yourself.
319
@end itemize
320
 
321
Many programs are designed to be extensible: they include an interpreter
322
for a language that is higher level than C.  Often much of the program
323
is written in that language, too.  The Emacs editor pioneered this
324
technique.
325
 
326
@cindex Guile
327
@cindex GNOME and Guile
328
The standard extensibility interpreter for GNU software is Guile
329
(@uref{http://www.gnu.org/@/software/@/guile/}), which implements the
330
language Scheme (an especially clean and simple dialect of Lisp).
331
Guile also includes bindings for GTK+/GNOME, making it practical to
332
write modern GUI functionality within Guile.  We don't reject programs
333
written in other ``scripting languages'' such as Perl and Python, but
334
using Guile is very important for the overall consistency of the GNU
335
system.
336
 
337
 
338
@node Compatibility
339
@section Compatibility with Other Implementations
340
@cindex compatibility with C and @sc{posix} standards
341
@cindex @sc{posix} compatibility
342
 
343
With occasional exceptions, utility programs and libraries for GNU
344
should be upward compatible with those in Berkeley Unix, and upward
345
compatible with Standard C if Standard C specifies their
346
behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
347
their behavior.
348
 
349
When these standards conflict, it is useful to offer compatibility
350
modes for each of them.
351
 
352
@cindex options for compatibility
353
Standard C and @sc{posix} prohibit many kinds of extensions.  Feel
354
free to make the extensions anyway, and include a @samp{--ansi},
355
@samp{--posix}, or @samp{--compatible} option to turn them off.
356
However, if the extension has a significant chance of breaking any real
357
programs or scripts, then it is not really upward compatible.  So you
358
should try to redesign its interface to make it upward compatible.
359
 
360
@cindex @code{POSIXLY_CORRECT}, environment variable
361
Many GNU programs suppress extensions that conflict with @sc{posix} if the
362
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
363
defined with a null value).  Please make your program recognize this
364
variable if appropriate.
365
 
366
When a feature is used only by users (not by programs or command
367
files), and it is done poorly in Unix, feel free to replace it
368
completely with something totally different and better.  (For example,
369
@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible
370
feature as well.  (There is a free @code{vi} clone, so we offer it.)
371
 
372
Additional useful features are welcome regardless of whether
373
there is any precedent for them.
374
 
375
@node Using Extensions
376
@section Using Non-standard Features
377
@cindex non-standard extensions
378
 
379
Many GNU facilities that already exist support a number of convenient
380
extensions over the comparable Unix facilities.  Whether to use these
381
extensions in implementing your program is a difficult question.
382
 
383
On the one hand, using the extensions can make a cleaner program.
384
On the other hand, people will not be able to build the program
385
unless the other GNU tools are available.  This might cause the
386
program to work on fewer kinds of machines.
387
 
388
With some extensions, it might be easy to provide both alternatives.
389
For example, you can define functions with a ``keyword'' @code{INLINE}
390
and define that as a macro to expand into either @code{inline} or
391
nothing, depending on the compiler.
392
 
393
In general, perhaps it is best not to use the extensions if you can
394
straightforwardly do without them, but to use the extensions if they
395
are a big improvement.
396
 
397
An exception to this rule are the large, established programs (such as
398
Emacs) which run on a great variety of systems.  Using GNU extensions in
399
such programs would make many users unhappy, so we don't do that.
400
 
401
Another exception is for programs that are used as part of compilation:
402
anything that must be compiled with other compilers in order to
403
bootstrap the GNU compilation facilities.  If these require the GNU
404
compiler, then no one can compile them without having them installed
405
already.  That would be extremely troublesome in certain cases.
406
 
407
@node Standard C
408
@section Standard C and Pre-Standard C
409
@cindex @sc{ansi} C standard
410
 
411
1989 Standard C is widespread enough now that it is ok to use its
412
features in new programs.  There is one exception: do not ever use the
413
``trigraph'' feature of Standard C.
414
 
415
1999 Standard C is not widespread yet, so please do not require its
416
features in programs.  It is ok to use its features if they are present.
417
 
418
However, it is easy to support pre-standard compilers in most programs,
419
so if you know how to do that, feel free.  If a program you are
420
maintaining has such support, you should try to keep it working.
421
 
422
@cindex function prototypes
423
To support pre-standard C, instead of writing function definitions in
424
standard prototype form,
425
 
426
@example
427
int
428
foo (int x, int y)
429
@dots{}
430
@end example
431
 
432
@noindent
433
write the definition in pre-standard style like this,
434
 
435
@example
436
int
437
foo (x, y)
438
     int x, y;
439
@dots{}
440
@end example
441
 
442
@noindent
443
and use a separate declaration to specify the argument prototype:
444
 
445
@example
446
int foo (int, int);
447
@end example
448
 
449
You need such a declaration anyway, in a header file, to get the benefit
450
of prototypes in all the files where the function is called.  And once
451
you have the declaration, you normally lose nothing by writing the
452
function definition in the pre-standard style.
453
 
454
This technique does not work for integer types narrower than @code{int}.
455
If you think of an argument as being of a type narrower than @code{int},
456
declare it as @code{int} instead.
457
 
458
There are a few special cases where this technique is hard to use.  For
459
example, if a function argument needs to hold the system type
460
@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
461
@code{int} on some machines; but you cannot use @code{int} instead,
462
because @code{dev_t} is wider than @code{int} on some machines.  There
463
is no type you can safely use on all machines in a non-standard
464
definition.  The only way to support non-standard C and pass such an
465
argument is to check the width of @code{dev_t} using Autoconf and choose
466
the argument type accordingly.  This may not be worth the trouble.
467
 
468
In order to support pre-standard compilers that do not recognize
469
prototypes, you may want to use a preprocessor macro like this:
470
 
471
@example
472
/* Declare the prototype for a general external function.  */
473
#if defined (__STDC__) || defined (WINDOWSNT)
474
#define P_(proto) proto
475
#else
476
#define P_(proto) ()
477
#endif
478
@end example
479
 
480
@node Conditional Compilation
481
@section Conditional Compilation
482
 
483
When supporting configuration options already known when building your
484
program we prefer using @code{if (... )} over conditional compilation,
485
as in the former case the compiler is able to perform more extensive
486
checking of all possible code paths.
487
 
488
For example, please write
489
 
490
@smallexample
491
  if (HAS_FOO)
492
    ...
493
  else
494
    ...
495
@end smallexample
496
 
497
@noindent
498
instead of:
499
 
500
@smallexample
501
  #ifdef HAS_FOO
502
    ...
503
  #else
504
    ...
505
  #endif
506
@end smallexample
507
 
508
A modern compiler such as GCC will generate exactly the same code in
509
both cases, and we have been using similar techniques with good success
510
in several projects.  Of course, the former method assumes that
511
@code{HAS_FOO} is defined as either 0 or 1.
512
 
513
While this is not a silver bullet solving all portability problems,
514
and is not always appropriate, following this policy would have saved
515
GCC developers many hours, or even days, per year.
516
 
517
In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
518
GCC which cannot be simply used in @code{if (...)} statements, there is
519
an easy workaround.  Simply introduce another macro
520
@code{HAS_REVERSIBLE_CC_MODE} as in the following example:
521
 
522
@smallexample
523
  #ifdef REVERSIBLE_CC_MODE
524
  #define HAS_REVERSIBLE_CC_MODE 1
525
  #else
526
  #define HAS_REVERSIBLE_CC_MODE 0
527
  #endif
528
@end smallexample
529
 
530
@node Program Behavior
531
@chapter Program Behavior for All Programs
532
 
533
This chapter describes conventions for writing robust
534
software.  It also describes general standards for error messages, the
535
command line interface, and how libraries should behave.
536
 
537
@menu
538
* Non-GNU Standards::           We consider standards such as POSIX;
539
                                  we don't "obey" them.
540
* Semantics::                   Writing robust programs.
541
* Libraries::                   Library behavior.
542
* Errors::                      Formatting error messages.
543
* User Interfaces::             Standards about interfaces generally.
544
* Graphical Interfaces::        Standards for graphical interfaces.
545
* Command-Line Interfaces::     Standards for command line interfaces.
546
* Option Table::                Table of long options.
547
* OID Allocations::             Table of OID slots for GNU.
548
* Memory Usage::                When and how to care about memory needs.
549
* File Usage::                  Which files to use, and where.
550
@end menu
551
 
552
@node Non-GNU Standards
553
@section Non-GNU Standards
554
 
555
The GNU Project regards standards published by other organizations as
556
suggestions, not orders.  We consider those standards, but we do not
557
``obey'' them.  In developing a GNU program, you should implement
558
an outside standard's specifications when that makes the GNU system
559
better overall in an objective sense.  When it doesn't, you shouldn't.
560
 
561
In most cases, following published standards is convenient for
562
users---it means that their programs or scripts will work more
563
portably.  For instance, GCC implements nearly all the features of
564
Standard C as specified by that standard.  C program developers would
565
be unhappy if it did not.  And GNU utilities mostly follow
566
specifications of POSIX.2; shell script writers and users would be
567
unhappy if our programs were incompatible.
568
 
569
But we do not follow either of these specifications rigidly, and there
570
are specific points on which we decided not to follow them, so as to
571
make the GNU system better for users.
572
 
573
For instance, Standard C says that nearly all extensions to C are
574
prohibited.  How silly!  GCC implements many extensions, some of which
575
were later adopted as part of the standard.  If you want these
576
constructs to give an error message as ``required'' by the standard,
577
you must specify @samp{--pedantic}, which was implemented only so that
578
we can say ``GCC is a 100% implementation of the standard,'' not
579
because there is any reason to actually use it.
580
 
581
POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
582
default in units of 512 bytes.  What users want is units of 1k, so
583
that is what we do by default.  If you want the ridiculous behavior
584
``required'' by POSIX, you must set the environment variable
585
@samp{POSIXLY_CORRECT} (which was originally going to be named
586
@samp{POSIX_ME_HARDER}).
587
 
588
GNU utilities also depart from the letter of the POSIX.2 specification
589
when they support long-named command-line options, and intermixing
590
options with ordinary arguments.  This minor incompatibility with
591
POSIX is never a problem in practice, and it is very useful.
592
 
593
In particular, don't reject a new feature, or remove an old one,
594
merely because a standard says it is ``forbidden'' or ``deprecated.''
595
 
596
@node Semantics
597
@section Writing Robust Programs
598
 
599
@cindex arbitrary limits on data
600
Avoid arbitrary limits on the length or number of @emph{any} data
601
structure, including file names, lines, files, and symbols, by allocating
602
all data structures dynamically.  In most Unix utilities, ``long lines
603
are silently truncated''.  This is not acceptable in a GNU utility.
604
 
605
@cindex @code{NUL} characters
606
Utilities reading files should not drop NUL characters, or any other
607
nonprinting characters @emph{including those with codes above 0177}.
608
The only sensible exceptions would be utilities specifically intended
609
for interface to certain types of terminals or printers
610
that can't handle those characters.
611
Whenever possible, try to make programs work properly with
612
sequences of bytes that represent multibyte characters, using encodings
613
such as UTF-8 and others.
614
 
615
@cindex error messages
616
Check every system call for an error return, unless you know you wish to
617
ignore errors.  Include the system error text (from @code{perror} or
618
equivalent) in @emph{every} error message resulting from a failing
619
system call, as well as the name of the file if any and the name of the
620
utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
621
sufficient.
622
 
623
@cindex @code{malloc} return value
624
@cindex memory allocation failure
625
Check every call to @code{malloc} or @code{realloc} to see if it
626
returned zero.  Check @code{realloc} even if you are making the block
627
smaller; in a system that rounds block sizes to a power of 2,
628
@code{realloc} may get a different block if you ask for less space.
629
 
630
In Unix, @code{realloc} can destroy the storage block if it returns
631
zero.  GNU @code{realloc} does not have this bug: if it fails, the
632
original block is unchanged.  Feel free to assume the bug is fixed.  If
633
you wish to run your program on Unix, and wish to avoid lossage in this
634
case, you can use the GNU @code{malloc}.
635
 
636
You must expect @code{free} to alter the contents of the block that was
637
freed.  Anything you want to fetch from the block, you must fetch before
638
calling @code{free}.
639
 
640
If @code{malloc} fails in a noninteractive program, make that a fatal
641
error.  In an interactive program (one that reads commands from the
642
user), it is better to abort the command and return to the command
643
reader loop.  This allows the user to kill other processes to free up
644
virtual memory, and then try the command again.
645
 
646
@cindex command-line arguments, decoding
647
Use @code{getopt_long} to decode arguments, unless the argument syntax
648
makes this unreasonable.
649
 
650
When static storage is to be written in during program execution, use
651
explicit C code to initialize it.  Reserve C initialized declarations
652
for data that will not be changed.
653
@c ADR: why?
654
 
655
Try to avoid low-level interfaces to obscure Unix data structures (such
656
as file directories, utmp, or the layout of kernel memory), since these
657
are less likely to work compatibly.  If you need to find all the files
658
in a directory, use @code{readdir} or some other high-level interface.
659
These are supported compatibly by GNU.
660
 
661
@cindex signal handling
662
The preferred signal handling facilities are the BSD variant of
663
@code{signal}, and the @sc{posix} @code{sigaction} function; the
664
alternative USG @code{signal} interface is an inferior design.
665
 
666
Nowadays, using the @sc{posix} signal functions may be the easiest way
667
to make a program portable.  If you use @code{signal}, then on GNU/Linux
668
systems running GNU libc version 1, you should include
669
@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
670
behavior.  It is up to you whether to support systems where
671
@code{signal} has only the USG behavior, or give up on them.
672
 
673
@cindex impossible conditions
674
In error checks that detect ``impossible'' conditions, just abort.
675
There is usually no point in printing any message.  These checks
676
indicate the existence of bugs.  Whoever wants to fix the bugs will have
677
to read the source code and run a debugger.  So explain the problem with
678
comments in the source.  The relevant data will be in variables, which
679
are easy to examine with the debugger, so there is no point moving them
680
elsewhere.
681
 
682
Do not use a count of errors as the exit status for a program.
683
@emph{That does not work}, because exit status values are limited to 8
684
bits (0 through 255).  A single run of the program might have 256
685
errors; if you try to return 256 as the exit status, the parent process
686
will see 0 as the status, and it will appear that the program succeeded.
687
 
688
@cindex temporary files
689
@cindex @code{TMPDIR} environment variable
690
If you make temporary files, check the @code{TMPDIR} environment
691
variable; if that variable is defined, use the specified directory
692
instead of @file{/tmp}.
693
 
694
In addition, be aware that there is a possible security problem when
695
creating temporary files in world-writable directories.  In C, you can
696
avoid this problem by creating temporary files in this manner:
697
 
698
@example
699
fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
700
@end example
701
 
702
@noindent
703
or by using the @code{mkstemps} function from libiberty.
704
 
705
In bash, use @code{set -C} to avoid this problem.
706
 
707
@node Libraries
708
@section Library Behavior
709
@cindex libraries
710
 
711
Try to make library functions reentrant.  If they need to do dynamic
712
storage allocation, at least try to avoid any nonreentrancy aside from
713
that of @code{malloc} itself.
714
 
715
Here are certain name conventions for libraries, to avoid name
716
conflicts.
717
 
718
Choose a name prefix for the library, more than two characters long.
719
All external function and variable names should start with this
720
prefix.  In addition, there should only be one of these in any given
721
library member.  This usually means putting each one in a separate
722
source file.
723
 
724
An exception can be made when two external symbols are always used
725
together, so that no reasonable program could use one without the
726
other; then they can both go in the same file.
727
 
728
External symbols that are not documented entry points for the user
729
should have names beginning with @samp{_}.  The @samp{_} should be
730
followed by the chosen name prefix for the library, to prevent
731
collisions with other libraries.  These can go in the same files with
732
user entry points if you like.
733
 
734
Static functions and variables can be used as you like and need not
735
fit any naming convention.
736
 
737
@node Errors
738
@section Formatting Error Messages
739
@cindex formatting error messages
740
@cindex error messages, formatting
741
 
742
Error messages from compilers should look like this:
743
 
744
@example
745
@var{source-file-name}:@var{lineno}: @var{message}
746
@end example
747
 
748
@noindent
749
If you want to mention the column number, use one of these formats:
750
 
751
@example
752
@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
753
@var{source-file-name}:@var{lineno}.@var{column}: @var{message}
754
 
755
@end example
756
 
757
@noindent
758
Line numbers should start from 1 at the beginning of the file, and
759
column numbers should start from 1 at the beginning of the line.  (Both
760
of these conventions are chosen for compatibility.)  Calculate column
761
numbers assuming that space and all ASCII printing characters have
762
equal width, and assuming tab stops every 8 columns.
763
 
764
The error message can also give both the starting and ending positions
765
of the erroneous text.  There are several formats so that you can
766
avoid redundant information such as a duplicate line number.
767
Here are the possible formats:
768
 
769
@example
770
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
771
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
772
@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
773
@end example
774
 
775
@noindent
776
When an error is spread over several files, you can use this format:
777
 
778
@example
779
@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
780
@end example
781
 
782
Error messages from other noninteractive programs should look like this:
783
 
784
@example
785
@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
786
@end example
787
 
788
@noindent
789
when there is an appropriate source file, or like this:
790
 
791
@example
792
@var{program}: @var{message}
793
@end example
794
 
795
@noindent
796
when there is no relevant source file.
797
 
798
If you want to mention the column number, use this format:
799
 
800
@example
801
@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
802
@end example
803
 
804
In an interactive program (one that is reading commands from a
805
terminal), it is better not to include the program name in an error
806
message.  The place to indicate which program is running is in the
807
prompt or with the screen layout.  (When the same program runs with
808
input from a source other than a terminal, it is not interactive and
809
would do best to print error messages using the noninteractive style.)
810
 
811
The string @var{message} should not begin with a capital letter when
812
it follows a program name and/or file name, because that isn't the
813
beginning of a sentence.  (The sentence conceptually starts at the
814
beginning of the line.)  Also, it should not end with a period.
815
 
816
Error messages from interactive programs, and other messages such as
817
usage messages, should start with a capital letter.  But they should not
818
end with a period.
819
 
820
@node User Interfaces
821
@section Standards for Interfaces Generally
822
 
823
@cindex program name and its behavior
824
@cindex behavior, dependent on program's name
825
Please don't make the behavior of a utility depend on the name used
826
to invoke it.  It is useful sometimes to make a link to a utility
827
with a different name, and that should not change what it does.
828
 
829
Instead, use a run time option or a compilation switch or both
830
to select among the alternate behaviors.
831
 
832
@cindex output device and program's behavior
833
Likewise, please don't make the behavior of the program depend on the
834
type of output device it is used with.  Device independence is an
835
important principle of the system's design; do not compromise it merely
836
to save someone from typing an option now and then.  (Variation in error
837
message syntax when using a terminal is ok, because that is a side issue
838
that people do not depend on.)
839
 
840
If you think one behavior is most useful when the output is to a
841
terminal, and another is most useful when the output is a file or a
842
pipe, then it is usually best to make the default behavior the one that
843
is useful with output to a terminal, and have an option for the other
844
behavior.
845
 
846
Compatibility requires certain programs to depend on the type of output
847
device.  It would be disastrous if @code{ls} or @code{sh} did not do so
848
in the way all users expect.  In some of these cases, we supplement the
849
program with a preferred alternate version that does not depend on the
850
output device type.  For example, we provide a @code{dir} program much
851
like @code{ls} except that its default output format is always
852
multi-column format.
853
 
854
 
855
@node Graphical Interfaces
856
@section Standards for Graphical Interfaces
857
@cindex graphical user interface
858
@cindex interface styles
859
@cindex user interface styles
860
 
861
@cindex GTK+
862
When you write a program that provides a graphical user interface,
863
please make it work with the X Window System and the GTK+ toolkit
864
unless the functionality specifically requires some alternative (for
865
example, ``displaying jpeg images while in console mode'').
866
 
867
In addition, please provide a command-line interface to control the
868
functionality.  (In many cases, the graphical user interface can be a
869
separate program which invokes the command-line program.)  This is
870
so that the same jobs can be done from scripts.
871
 
872
@cindex CORBA
873
@cindex GNOME
874
@cindex D-bus
875
@cindex keyboard interface
876
@cindex library interface
877
Please also consider providing a D-bus interface for use from other
878
running programs, such as within GNOME.  (GNOME used to use CORBA
879
for this, but that is being phased out.)  In addition, consider
880
providing a library interface (for use from C), and perhaps a
881
keyboard-driven console interface (for use by users from console
882
mode).  Once you are doing the work to provide the functionality and
883
the graphical interface, these won't be much extra work.
884
 
885
 
886
@node Command-Line Interfaces
887
@section Standards for Command Line Interfaces
888
@cindex command-line interface
889
 
890
@findex getopt
891
It is a good idea to follow the @sc{posix} guidelines for the
892
command-line options of a program.  The easiest way to do this is to use
893
@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
894
will normally permit options anywhere among the arguments unless the
895
special argument @samp{--} is used.  This is not what @sc{posix}
896
specifies; it is a GNU extension.
897
 
898
@cindex long-named options
899
Please define long-named options that are equivalent to the
900
single-letter Unix-style options.  We hope to make GNU more user
901
friendly this way.  This is easy to do with the GNU function
902
@code{getopt_long}.
903
 
904
One of the advantages of long-named options is that they can be
905
consistent from program to program.  For example, users should be able
906
to expect the ``verbose'' option of any GNU program which has one, to be
907
spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
908
the table of common long-option names when you choose the option names
909
for your program (@pxref{Option Table}).
910
 
911
It is usually a good idea for file names given as ordinary arguments to
912
be input files only; any output files would be specified using options
913
(preferably @samp{-o} or @samp{--output}).  Even if you allow an output
914
file name as an ordinary argument for compatibility, try to provide an
915
option as another way to specify it.  This will lead to more consistency
916
among GNU utilities, and fewer idiosyncrasies for users to remember.
917
 
918
@cindex standard command-line options
919
@cindex options, standard command-line
920
@cindex CGI programs, standard options for
921
@cindex PATH_INFO, specifying standard options as
922
All programs should support two standard options: @samp{--version}
923
and @samp{--help}.  CGI programs should accept these as command-line
924
options, and also if given as the @env{PATH_INFO}; for instance,
925
visiting @url{http://example.org/p.cgi/--help} in a browser should
926
output the same information as invoking @samp{p.cgi --help} from the
927
command line.
928
 
929
@menu
930
* --version::       The standard output for --version.
931
* --help::          The standard output for --help.
932
@end menu
933
 
934
@node --version
935
@subsection @option{--version}
936
 
937
@cindex @samp{--version} output
938
 
939
The standard @code{--version} option should direct the program to
940
print information about its name, version, origin and legal status,
941
all on standard output, and then exit successfully.  Other options and
942
arguments should be ignored once this is seen, and the program should
943
not perform its normal function.
944
 
945
@cindex canonical name of a program
946
@cindex program's canonical name
947
The first line is meant to be easy for a program to parse; the version
948
number proper starts after the last space.  In addition, it contains
949
the canonical name for this program, in this format:
950
 
951
@example
952
GNU Emacs 19.30
953
@end example
954
 
955
@noindent
956
The program's name should be a constant string; @emph{don't} compute it
957
from @code{argv[0]}.  The idea is to state the standard or canonical
958
name for the program, not its file name.  There are other ways to find
959
out the precise file name where a command is found in @code{PATH}.
960
 
961
If the program is a subsidiary part of a larger package, mention the
962
package name in parentheses, like this:
963
 
964
@example
965
emacsserver (GNU Emacs) 19.30
966
@end example
967
 
968
@noindent
969
If the package has a version number which is different from this
970
program's version number, you can mention the package version number
971
just before the close-parenthesis.
972
 
973
If you @emph{need} to mention the version numbers of libraries which
974
are distributed separately from the package which contains this program,
975
you can do so by printing an additional line of version info for each
976
library you want to mention.  Use the same format for these lines as for
977
the first line.
978
 
979
Please do not mention all of the libraries that the program uses ``just
980
for completeness''---that would produce a lot of unhelpful clutter.
981
Please mention library version numbers only if you find in practice that
982
they are very important to you in debugging.
983
 
984
The following line, after the version number line or lines, should be a
985
copyright notice.  If more than one copyright notice is called for, put
986
each on a separate line.
987
 
988
Next should follow a line stating the license, preferably using one of
989
abbrevations below, and a brief statement that the program is free
990
software, and that users are free to copy and change it.  Also mention
991
that there is no warranty, to the extent permitted by law.  See
992
recommended wording below.
993
 
994
It is ok to finish the output with a list of the major authors of the
995
program, as a way of giving credit.
996
 
997
Here's an example of output that follows these rules:
998
 
999
@smallexample
1000
GNU hello 2.3
1001
Copyright (C) 2007 Free Software Foundation, Inc.
1002
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1003
This is free software: you are free to change and redistribute it.
1004
There is NO WARRANTY, to the extent permitted by law.
1005
@end smallexample
1006
 
1007
You should adapt this to your program, of course, filling in the proper
1008
year, copyright holder, name of program, and the references to
1009
distribution terms, and changing the rest of the wording as necessary.
1010
 
1011
This copyright notice only needs to mention the most recent year in
1012
which changes were made---there's no need to list the years for previous
1013
versions' changes.  You don't have to mention the name of the program in
1014
these notices, if that is inconvenient, since it appeared in the first
1015
line.  (The rules are different for copyright notices in source files;
1016
@pxref{Copyright Notices,,,maintain,Information for GNU Maintainers}.)
1017
 
1018
Translations of the above lines must preserve the validity of the
1019
copyright notices (@pxref{Internationalization}).  If the translation's
1020
character set supports it, the @samp{(C)} should be replaced with the
1021
copyright symbol, as follows:
1022
 
1023
@ifinfo
1024
(the official copyright symbol, which is the letter C in a circle);
1025
@end ifinfo
1026
@ifnotinfo
1027
@copyright{}
1028
@end ifnotinfo
1029
 
1030
Write the word ``Copyright'' exactly like that, in English.  Do not
1031
translate it into another language.  International treaties recognize
1032
the English word ``Copyright''; translations into other languages do not
1033
have legal significance.
1034
 
1035
Finally, here is the table of our suggested license abbreviations.
1036
Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning
1037
that particular version, or later versions with the @samp{+}, as shown
1038
above.
1039
 
1040
In the case of exceptions for extra permissions with the GPL, we use
1041
@samp{/} for a separator; the version number can follow the license
1042
abbreviation as usual, as in the examples below.
1043
 
1044
@table @asis
1045
@item GPL
1046
GNU General Public License, @url{http://www.gnu.org/@/licenses/@/gpl.html}.
1047
 
1048
@item LGPL
1049
GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}.
1050
 
1051
@item GPL/Ada
1052
GNU GPL with the exception for Ada.
1053
 
1054
@item Apache
1055
The Apache Software Foundation license,
1056
@url{http://www.apache.org/@/licenses}.
1057
 
1058
@item Artistic
1059
The Artistic license used for Perl, @url{http://www.perlfoundation.org/@/legal}.
1060
 
1061
@item Expat
1062
The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}.
1063
 
1064
@item MPL
1065
The Mozilla Public License, @url{http://www.mozilla.org/@/MPL/}.
1066
 
1067
@item OBSD
1068
The original (4-clause) BSD license, incompatible with the GNU GPL
1069
@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#6}.
1070
 
1071
@item PHP
1072
The license used for PHP, @url{http://www.php.net/@/license/}.
1073
 
1074
@item public domain
1075
The non-license that is being in the public domain,
1076
@url{http://www.gnu.org/@/licenses/@/license-list.html#PublicDomain}.
1077
 
1078
@item Python
1079
The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}.
1080
 
1081
@item RBSD
1082
The revised (3-clause) BSD, compatible with the GNU GPL,@*
1083
@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}.
1084
 
1085
@item X11
1086
The simple non-copyleft license used for most versions of the X Window
1087
System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
1088
 
1089
@item Zlib
1090
The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
1091
 
1092
@end table
1093
 
1094
More information about these licenses and many more are on the GNU
1095
licensing web pages,
1096
@url{http://www.gnu.org/@/licenses/@/license-list.html}.
1097
 
1098
 
1099
@node --help
1100
@subsection @option{--help}
1101
 
1102
@cindex @samp{--help} output
1103
 
1104
The standard @code{--help} option should output brief documentation
1105
for how to invoke the program, on standard output, then exit
1106
successfully.  Other options and arguments should be ignored once this
1107
is seen, and the program should not perform its normal function.
1108
 
1109
@cindex address for bug reports
1110
@cindex bug reports
1111
Near the end of the @samp{--help} option's output, please place lines
1112
giving the email address for bug reports, the package's home page
1113
(normally @indicateurl{http://www.gnu.org/software/@var{pkg}}, and the
1114
general page for help using GNU programs.  The format should be like this:
1115
 
1116
@example
1117
Report bugs to: @var{mailing-address}
1118
@var{pkg} home page: <http://www.gnu.org/software/@var{pkg}/>
1119
General help using GNU software: <http://www.gnu.org/gethelp/>
1120
@end example
1121
 
1122
It is ok to mention other appropriate mailing lists and web pages.
1123
 
1124
 
1125
@node Option Table
1126
@section Table of Long Options
1127
@cindex long option names
1128
@cindex table of long options
1129
 
1130
Here is a table of long options used by GNU programs.  It is surely
1131
incomplete, but we aim to list all the options that a new program might
1132
want to be compatible with.  If you use names not already in the table,
1133
please send @email{bug-standards@@gnu.org} a list of them, with their
1134
meanings, so we can update the table.
1135
 
1136
@c Please leave newlines between items in this table; it's much easier
1137
@c to update when it isn't completely squashed together and unreadable.
1138
@c When there is more than one short option for a long option name, put
1139
@c a semicolon between the lists of the programs that use them, not a
1140
@c period.   --friedman
1141
 
1142
@table @samp
1143
@item after-date
1144
@samp{-N} in @code{tar}.
1145
 
1146
@item all
1147
@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
1148
and @code{unexpand}.
1149
 
1150
@item all-text
1151
@samp{-a} in @code{diff}.
1152
 
1153
@item almost-all
1154
@samp{-A} in @code{ls}.
1155
 
1156
@item append
1157
@samp{-a} in @code{etags}, @code{tee}, @code{time};
1158
@samp{-r} in @code{tar}.
1159
 
1160
@item archive
1161
@samp{-a} in @code{cp}.
1162
 
1163
@item archive-name
1164
@samp{-n} in @code{shar}.
1165
 
1166
@item arglength
1167
@samp{-l} in @code{m4}.
1168
 
1169
@item ascii
1170
@samp{-a} in @code{diff}.
1171
 
1172
@item assign
1173
@samp{-v} in @code{gawk}.
1174
 
1175
@item assume-new
1176
@samp{-W} in @code{make}.
1177
 
1178
@item assume-old
1179
@samp{-o} in @code{make}.
1180
 
1181
@item auto-check
1182
@samp{-a} in @code{recode}.
1183
 
1184
@item auto-pager
1185
@samp{-a} in @code{wdiff}.
1186
 
1187
@item auto-reference
1188
@samp{-A} in @code{ptx}.
1189
 
1190
@item avoid-wraps
1191
@samp{-n} in @code{wdiff}.
1192
 
1193
@item background
1194
For server programs, run in the background.
1195
 
1196
@item backward-search
1197
@samp{-B} in @code{ctags}.
1198
 
1199
@item basename
1200
@samp{-f} in @code{shar}.
1201
 
1202
@item batch
1203
Used in GDB.
1204
 
1205
@item baud
1206
Used in GDB.
1207
 
1208
@item before
1209
@samp{-b} in @code{tac}.
1210
 
1211
@item binary
1212
@samp{-b} in @code{cpio} and @code{diff}.
1213
 
1214
@item bits-per-code
1215
@samp{-b} in @code{shar}.
1216
 
1217
@item block-size
1218
Used in @code{cpio} and @code{tar}.
1219
 
1220
@item blocks
1221
@samp{-b} in @code{head} and @code{tail}.
1222
 
1223
@item break-file
1224
@samp{-b} in @code{ptx}.
1225
 
1226
@item brief
1227
Used in various programs to make output shorter.
1228
 
1229
@item bytes
1230
@samp{-c} in @code{head}, @code{split}, and @code{tail}.
1231
 
1232
@item c@t{++}
1233
@samp{-C} in @code{etags}.
1234
 
1235
@item catenate
1236
@samp{-A} in @code{tar}.
1237
 
1238
@item cd
1239
Used in various programs to specify the directory to use.
1240
 
1241
@item changes
1242
@samp{-c} in @code{chgrp} and @code{chown}.
1243
 
1244
@item classify
1245
@samp{-F} in @code{ls}.
1246
 
1247
@item colons
1248
@samp{-c} in @code{recode}.
1249
 
1250
@item command
1251
@samp{-c} in @code{su};
1252
@samp{-x} in GDB.
1253
 
1254
@item compare
1255
@samp{-d} in @code{tar}.
1256
 
1257
@item compat
1258
Used in @code{gawk}.
1259
 
1260
@item compress
1261
@samp{-Z} in @code{tar} and @code{shar}.
1262
 
1263
@item concatenate
1264
@samp{-A} in @code{tar}.
1265
 
1266
@item confirmation
1267
@samp{-w} in @code{tar}.
1268
 
1269
@item context
1270
Used in @code{diff}.
1271
 
1272
@item copyleft
1273
@samp{-W copyleft} in @code{gawk}.
1274
 
1275
@item copyright
1276
@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
1277
@samp{-W copyright} in @code{gawk}.
1278
 
1279
@item core
1280
Used in GDB.
1281
 
1282
@item count
1283
@samp{-q} in @code{who}.
1284
 
1285
@item count-links
1286
@samp{-l} in @code{du}.
1287
 
1288
@item create
1289
Used in @code{tar} and @code{cpio}.
1290
 
1291
@item cut-mark
1292
@samp{-c} in @code{shar}.
1293
 
1294
@item cxref
1295
@samp{-x} in @code{ctags}.
1296
 
1297
@item date
1298
@samp{-d} in @code{touch}.
1299
 
1300
@item debug
1301
@samp{-d} in @code{make} and @code{m4};
1302
@samp{-t} in Bison.
1303
 
1304
@item define
1305
@samp{-D} in @code{m4}.
1306
 
1307
@item defines
1308
@samp{-d} in Bison and @code{ctags}.
1309
 
1310
@item delete
1311
@samp{-D} in @code{tar}.
1312
 
1313
@item dereference
1314
@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
1315
@code{ls}, and @code{tar}.
1316
 
1317
@item dereference-args
1318
@samp{-D} in @code{du}.
1319
 
1320
@item device
1321
Specify an I/O device (special file name).
1322
 
1323
@item diacritics
1324
@samp{-d} in @code{recode}.
1325
 
1326
@item dictionary-order
1327
@samp{-d} in @code{look}.
1328
 
1329
@item diff
1330
@samp{-d} in @code{tar}.
1331
 
1332
@item digits
1333
@samp{-n} in @code{csplit}.
1334
 
1335
@item directory
1336
Specify the directory to use, in various programs.  In @code{ls}, it
1337
means to show directories themselves rather than their contents.  In
1338
@code{rm} and @code{ln}, it means to not treat links to directories
1339
specially.
1340
 
1341
@item discard-all
1342
@samp{-x} in @code{strip}.
1343
 
1344
@item discard-locals
1345
@samp{-X} in @code{strip}.
1346
 
1347
@item dry-run
1348
@samp{-n} in @code{make}.
1349
 
1350
@item ed
1351
@samp{-e} in @code{diff}.
1352
 
1353
@item elide-empty-files
1354
@samp{-z} in @code{csplit}.
1355
 
1356
@item end-delete
1357
@samp{-x} in @code{wdiff}.
1358
 
1359
@item end-insert
1360
@samp{-z} in @code{wdiff}.
1361
 
1362
@item entire-new-file
1363
@samp{-N} in @code{diff}.
1364
 
1365
@item environment-overrides
1366
@samp{-e} in @code{make}.
1367
 
1368
@item eof
1369
@samp{-e} in @code{xargs}.
1370
 
1371
@item epoch
1372
Used in GDB.
1373
 
1374
@item error-limit
1375
Used in @code{makeinfo}.
1376
 
1377
@item error-output
1378
@samp{-o} in @code{m4}.
1379
 
1380
@item escape
1381
@samp{-b} in @code{ls}.
1382
 
1383
@item exclude-from
1384
@samp{-X} in @code{tar}.
1385
 
1386
@item exec
1387
Used in GDB.
1388
 
1389
@item exit
1390
@samp{-x} in @code{xargs}.
1391
 
1392
@item exit-0
1393
@samp{-e} in @code{unshar}.
1394
 
1395
@item expand-tabs
1396
@samp{-t} in @code{diff}.
1397
 
1398
@item expression
1399
@samp{-e} in @code{sed}.
1400
 
1401
@item extern-only
1402
@samp{-g} in @code{nm}.
1403
 
1404
@item extract
1405
@samp{-i} in @code{cpio};
1406
@samp{-x} in @code{tar}.
1407
 
1408
@item faces
1409
@samp{-f} in @code{finger}.
1410
 
1411
@item fast
1412
@samp{-f} in @code{su}.
1413
 
1414
@item fatal-warnings
1415
@samp{-E} in @code{m4}.
1416
 
1417
@item file
1418
@samp{-f} in @code{gawk}, @code{info}, @code{make}, @code{mt},
1419
@code{sed}, and @code{tar}.
1420
 
1421
@item field-separator
1422
@samp{-F} in @code{gawk}.
1423
 
1424
@item file-prefix
1425
@samp{-b} in Bison.
1426
 
1427
@item file-type
1428
@samp{-F} in @code{ls}.
1429
 
1430
@item files-from
1431
@samp{-T} in @code{tar}.
1432
 
1433
@item fill-column
1434
Used in @code{makeinfo}.
1435
 
1436
@item flag-truncation
1437
@samp{-F} in @code{ptx}.
1438
 
1439
@item fixed-output-files
1440
@samp{-y} in Bison.
1441
 
1442
@item follow
1443
@samp{-f} in @code{tail}.
1444
 
1445
@item footnote-style
1446
Used in @code{makeinfo}.
1447
 
1448
@item force
1449
@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
1450
 
1451
@item force-prefix
1452
@samp{-F} in @code{shar}.
1453
 
1454
@item foreground
1455
For server programs, run in the foreground;
1456
in other words, don't do anything special to run the server
1457
in the background.
1458
 
1459
@item format
1460
Used in @code{ls}, @code{time}, and @code{ptx}.
1461
 
1462
@item freeze-state
1463
@samp{-F} in @code{m4}.
1464
 
1465
@item fullname
1466
Used in GDB.
1467
 
1468
@item gap-size
1469
@samp{-g} in @code{ptx}.
1470
 
1471
@item get
1472
@samp{-x} in @code{tar}.
1473
 
1474
@item graphic
1475
@samp{-i} in @code{ul}.
1476
 
1477
@item graphics
1478
@samp{-g} in @code{recode}.
1479
 
1480
@item group
1481
@samp{-g} in @code{install}.
1482
 
1483
@item gzip
1484
@samp{-z} in @code{tar} and @code{shar}.
1485
 
1486
@item hashsize
1487
@samp{-H} in @code{m4}.
1488
 
1489
@item header
1490
@samp{-h} in @code{objdump} and @code{recode}
1491
 
1492
@item heading
1493
@samp{-H} in @code{who}.
1494
 
1495
@item help
1496
Used to ask for brief usage information.
1497
 
1498
@item here-delimiter
1499
@samp{-d} in @code{shar}.
1500
 
1501
@item hide-control-chars
1502
@samp{-q} in @code{ls}.
1503
 
1504
@item html
1505
In @code{makeinfo}, output HTML.
1506
 
1507
@item idle
1508
@samp{-u} in @code{who}.
1509
 
1510
@item ifdef
1511
@samp{-D} in @code{diff}.
1512
 
1513
@item ignore
1514
@samp{-I} in @code{ls};
1515
@samp{-x} in @code{recode}.
1516
 
1517
@item ignore-all-space
1518
@samp{-w} in @code{diff}.
1519
 
1520
@item ignore-backups
1521
@samp{-B} in @code{ls}.
1522
 
1523
@item ignore-blank-lines
1524
@samp{-B} in @code{diff}.
1525
 
1526
@item ignore-case
1527
@samp{-f} in @code{look} and @code{ptx};
1528
@samp{-i} in @code{diff} and @code{wdiff}.
1529
 
1530
@item ignore-errors
1531
@samp{-i} in @code{make}.
1532
 
1533
@item ignore-file
1534
@samp{-i} in @code{ptx}.
1535
 
1536
@item ignore-indentation
1537
@samp{-I} in @code{etags}.
1538
 
1539
@item ignore-init-file
1540
@samp{-f} in Oleo.
1541
 
1542
@item ignore-interrupts
1543
@samp{-i} in @code{tee}.
1544
 
1545
@item ignore-matching-lines
1546
@samp{-I} in @code{diff}.
1547
 
1548
@item ignore-space-change
1549
@samp{-b} in @code{diff}.
1550
 
1551
@item ignore-zeros
1552
@samp{-i} in @code{tar}.
1553
 
1554
@item include
1555
@samp{-i} in @code{etags};
1556
@samp{-I} in @code{m4}.
1557
 
1558
@item include-dir
1559
@samp{-I} in @code{make}.
1560
 
1561
@item incremental
1562
@samp{-G} in @code{tar}.
1563
 
1564
@item info
1565
@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
1566
 
1567
@item init-file
1568
In some programs, specify the name of the file to read as the user's
1569
init file.
1570
 
1571
@item initial
1572
@samp{-i} in @code{expand}.
1573
 
1574
@item initial-tab
1575
@samp{-T} in @code{diff}.
1576
 
1577
@item inode
1578
@samp{-i} in @code{ls}.
1579
 
1580
@item interactive
1581
@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
1582
@samp{-e} in @code{m4};
1583
@samp{-p} in @code{xargs};
1584
@samp{-w} in @code{tar}.
1585
 
1586
@item intermix-type
1587
@samp{-p} in @code{shar}.
1588
 
1589
@item iso-8601
1590
Used in @code{date}
1591
 
1592
@item jobs
1593
@samp{-j} in @code{make}.
1594
 
1595
@item just-print
1596
@samp{-n} in @code{make}.
1597
 
1598
@item keep-going
1599
@samp{-k} in @code{make}.
1600
 
1601
@item keep-files
1602
@samp{-k} in @code{csplit}.
1603
 
1604
@item kilobytes
1605
@samp{-k} in @code{du} and @code{ls}.
1606
 
1607
@item language
1608
@samp{-l} in @code{etags}.
1609
 
1610
@item less-mode
1611
@samp{-l} in @code{wdiff}.
1612
 
1613
@item level-for-gzip
1614
@samp{-g} in @code{shar}.
1615
 
1616
@item line-bytes
1617
@samp{-C} in @code{split}.
1618
 
1619
@item lines
1620
Used in @code{split}, @code{head}, and @code{tail}.
1621
 
1622
@item link
1623
@samp{-l} in @code{cpio}.
1624
 
1625
@item lint
1626
@itemx lint-old
1627
Used in @code{gawk}.
1628
 
1629
@item list
1630
@samp{-t} in @code{cpio};
1631
@samp{-l} in @code{recode}.
1632
 
1633
@item list
1634
@samp{-t} in @code{tar}.
1635
 
1636
@item literal
1637
@samp{-N} in @code{ls}.
1638
 
1639
@item load-average
1640
@samp{-l} in @code{make}.
1641
 
1642
@item login
1643
Used in @code{su}.
1644
 
1645
@item machine
1646
Used in @code{uname}.
1647
 
1648
@item macro-name
1649
@samp{-M} in @code{ptx}.
1650
 
1651
@item mail
1652
@samp{-m} in @code{hello} and @code{uname}.
1653
 
1654
@item make-directories
1655
@samp{-d} in @code{cpio}.
1656
 
1657
@item makefile
1658
@samp{-f} in @code{make}.
1659
 
1660
@item mapped
1661
Used in GDB.
1662
 
1663
@item max-args
1664
@samp{-n} in @code{xargs}.
1665
 
1666
@item max-chars
1667
@samp{-n} in @code{xargs}.
1668
 
1669
@item max-lines
1670
@samp{-l} in @code{xargs}.
1671
 
1672
@item max-load
1673
@samp{-l} in @code{make}.
1674
 
1675
@item max-procs
1676
@samp{-P} in @code{xargs}.
1677
 
1678
@item mesg
1679
@samp{-T} in @code{who}.
1680
 
1681
@item message
1682
@samp{-T} in @code{who}.
1683
 
1684
@item minimal
1685
@samp{-d} in @code{diff}.
1686
 
1687
@item mixed-uuencode
1688
@samp{-M} in @code{shar}.
1689
 
1690
@item mode
1691
@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
1692
 
1693
@item modification-time
1694
@samp{-m} in @code{tar}.
1695
 
1696
@item multi-volume
1697
@samp{-M} in @code{tar}.
1698
 
1699
@item name-prefix
1700
@samp{-a} in Bison.
1701
 
1702
@item nesting-limit
1703
@samp{-L} in @code{m4}.
1704
 
1705
@item net-headers
1706
@samp{-a} in @code{shar}.
1707
 
1708
@item new-file
1709
@samp{-W} in @code{make}.
1710
 
1711
@item no-builtin-rules
1712
@samp{-r} in @code{make}.
1713
 
1714
@item no-character-count
1715
@samp{-w} in @code{shar}.
1716
 
1717
@item no-check-existing
1718
@samp{-x} in @code{shar}.
1719
 
1720
@item no-common
1721
@samp{-3} in @code{wdiff}.
1722
 
1723
@item no-create
1724
@samp{-c} in @code{touch}.
1725
 
1726
@item no-defines
1727
@samp{-D} in @code{etags}.
1728
 
1729
@item no-deleted
1730
@samp{-1} in @code{wdiff}.
1731
 
1732
@item no-dereference
1733
@samp{-d} in @code{cp}.
1734
 
1735
@item no-inserted
1736
@samp{-2} in @code{wdiff}.
1737
 
1738
@item no-keep-going
1739
@samp{-S} in @code{make}.
1740
 
1741
@item no-lines
1742
@samp{-l} in Bison.
1743
 
1744
@item no-piping
1745
@samp{-P} in @code{shar}.
1746
 
1747
@item no-prof
1748
@samp{-e} in @code{gprof}.
1749
 
1750
@item no-regex
1751
@samp{-R} in @code{etags}.
1752
 
1753
@item no-sort
1754
@samp{-p} in @code{nm}.
1755
 
1756
@item no-splash
1757
Don't print a startup splash screen.
1758
 
1759
@item no-split
1760
Used in @code{makeinfo}.
1761
 
1762
@item no-static
1763
@samp{-a} in @code{gprof}.
1764
 
1765
@item no-time
1766
@samp{-E} in @code{gprof}.
1767
 
1768
@item no-timestamp
1769
@samp{-m} in @code{shar}.
1770
 
1771
@item no-validate
1772
Used in @code{makeinfo}.
1773
 
1774
@item no-wait
1775
Used in @code{emacsclient}.
1776
 
1777
@item no-warn
1778
Used in various programs to inhibit warnings.
1779
 
1780
@item node
1781
@samp{-n} in @code{info}.
1782
 
1783
@item nodename
1784
@samp{-n} in @code{uname}.
1785
 
1786
@item nonmatching
1787
@samp{-f} in @code{cpio}.
1788
 
1789
@item nstuff
1790
@samp{-n} in @code{objdump}.
1791
 
1792
@item null
1793
@samp{-0} in @code{xargs}.
1794
 
1795
@item number
1796
@samp{-n} in @code{cat}.
1797
 
1798
@item number-nonblank
1799
@samp{-b} in @code{cat}.
1800
 
1801
@item numeric-sort
1802
@samp{-n} in @code{nm}.
1803
 
1804
@item numeric-uid-gid
1805
@samp{-n} in @code{cpio} and @code{ls}.
1806
 
1807
@item nx
1808
Used in GDB.
1809
 
1810
@item old-archive
1811
@samp{-o} in @code{tar}.
1812
 
1813
@item old-file
1814
@samp{-o} in @code{make}.
1815
 
1816
@item one-file-system
1817
@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
1818
 
1819
@item only-file
1820
@samp{-o} in @code{ptx}.
1821
 
1822
@item only-prof
1823
@samp{-f} in @code{gprof}.
1824
 
1825
@item only-time
1826
@samp{-F} in @code{gprof}.
1827
 
1828
@item options
1829
@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
1830
@code{fdmountd}, and @code{fdumount}.
1831
 
1832
@item output
1833
In various programs, specify the output file name.
1834
 
1835
@item output-prefix
1836
@samp{-o} in @code{shar}.
1837
 
1838
@item override
1839
@samp{-o} in @code{rm}.
1840
 
1841
@item overwrite
1842
@samp{-c} in @code{unshar}.
1843
 
1844
@item owner
1845
@samp{-o} in @code{install}.
1846
 
1847
@item paginate
1848
@samp{-l} in @code{diff}.
1849
 
1850
@item paragraph-indent
1851
Used in @code{makeinfo}.
1852
 
1853
@item parents
1854
@samp{-p} in @code{mkdir} and @code{rmdir}.
1855
 
1856
@item pass-all
1857
@samp{-p} in @code{ul}.
1858
 
1859
@item pass-through
1860
@samp{-p} in @code{cpio}.
1861
 
1862
@item port
1863
@samp{-P} in @code{finger}.
1864
 
1865
@item portability
1866
@samp{-c} in @code{cpio} and @code{tar}.
1867
 
1868
@item posix
1869
Used in @code{gawk}.
1870
 
1871
@item prefix-builtins
1872
@samp{-P} in @code{m4}.
1873
 
1874
@item prefix
1875
@samp{-f} in @code{csplit}.
1876
 
1877
@item preserve
1878
Used in @code{tar} and @code{cp}.
1879
 
1880
@item preserve-environment
1881
@samp{-p} in @code{su}.
1882
 
1883
@item preserve-modification-time
1884
@samp{-m} in @code{cpio}.
1885
 
1886
@item preserve-order
1887
@samp{-s} in @code{tar}.
1888
 
1889
@item preserve-permissions
1890
@samp{-p} in @code{tar}.
1891
 
1892
@item print
1893
@samp{-l} in @code{diff}.
1894
 
1895
@item print-chars
1896
@samp{-L} in @code{cmp}.
1897
 
1898
@item print-data-base
1899
@samp{-p} in @code{make}.
1900
 
1901
@item print-directory
1902
@samp{-w} in @code{make}.
1903
 
1904
@item print-file-name
1905
@samp{-o} in @code{nm}.
1906
 
1907
@item print-symdefs
1908
@samp{-s} in @code{nm}.
1909
 
1910
@item printer
1911
@samp{-p} in @code{wdiff}.
1912
 
1913
@item prompt
1914
@samp{-p} in @code{ed}.
1915
 
1916
@item proxy
1917
Specify an HTTP proxy.
1918
 
1919
@item query-user
1920
@samp{-X} in @code{shar}.
1921
 
1922
@item question
1923
@samp{-q} in @code{make}.
1924
 
1925
@item quiet
1926
Used in many programs to inhibit the usual output.  Every
1927
program accepting @samp{--quiet} should accept @samp{--silent} as a
1928
synonym.
1929
 
1930
@item quiet-unshar
1931
@samp{-Q} in @code{shar}
1932
 
1933
@item quote-name
1934
@samp{-Q} in @code{ls}.
1935
 
1936
@item rcs
1937
@samp{-n} in @code{diff}.
1938
 
1939
@item re-interval
1940
Used in @code{gawk}.
1941
 
1942
@item read-full-blocks
1943
@samp{-B} in @code{tar}.
1944
 
1945
@item readnow
1946
Used in GDB.
1947
 
1948
@item recon
1949
@samp{-n} in @code{make}.
1950
 
1951
@item record-number
1952
@samp{-R} in @code{tar}.
1953
 
1954
@item recursive
1955
Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
1956
and @code{rm}.
1957
 
1958
@item reference
1959
@samp{-r} in @code{touch}.
1960
 
1961
@item references
1962
@samp{-r} in @code{ptx}.
1963
 
1964
@item regex
1965
@samp{-r} in @code{tac} and @code{etags}.
1966
 
1967
@item release
1968
@samp{-r} in @code{uname}.
1969
 
1970
@item reload-state
1971
@samp{-R} in @code{m4}.
1972
 
1973
@item relocation
1974
@samp{-r} in @code{objdump}.
1975
 
1976
@item rename
1977
@samp{-r} in @code{cpio}.
1978
 
1979
@item replace
1980
@samp{-i} in @code{xargs}.
1981
 
1982
@item report-identical-files
1983
@samp{-s} in @code{diff}.
1984
 
1985
@item reset-access-time
1986
@samp{-a} in @code{cpio}.
1987
 
1988
@item reverse
1989
@samp{-r} in @code{ls} and @code{nm}.
1990
 
1991
@item reversed-ed
1992
@samp{-f} in @code{diff}.
1993
 
1994
@item right-side-defs
1995
@samp{-R} in @code{ptx}.
1996
 
1997
@item same-order
1998
@samp{-s} in @code{tar}.
1999
 
2000
@item same-permissions
2001
@samp{-p} in @code{tar}.
2002
 
2003
@item save
2004
@samp{-g} in @code{stty}.
2005
 
2006
@item se
2007
Used in GDB.
2008
 
2009
@item sentence-regexp
2010
@samp{-S} in @code{ptx}.
2011
 
2012
@item separate-dirs
2013
@samp{-S} in @code{du}.
2014
 
2015
@item separator
2016
@samp{-s} in @code{tac}.
2017
 
2018
@item sequence
2019
Used by @code{recode} to chose files or pipes for sequencing passes.
2020
 
2021
@item shell
2022
@samp{-s} in @code{su}.
2023
 
2024
@item show-all
2025
@samp{-A} in @code{cat}.
2026
 
2027
@item show-c-function
2028
@samp{-p} in @code{diff}.
2029
 
2030
@item show-ends
2031
@samp{-E} in @code{cat}.
2032
 
2033
@item show-function-line
2034
@samp{-F} in @code{diff}.
2035
 
2036
@item show-tabs
2037
@samp{-T} in @code{cat}.
2038
 
2039
@item silent
2040
Used in many programs to inhibit the usual output.
2041
Every program accepting
2042
@samp{--silent} should accept @samp{--quiet} as a synonym.
2043
 
2044
@item size
2045
@samp{-s} in @code{ls}.
2046
 
2047
@item socket
2048
Specify a file descriptor for a network server to use for its socket,
2049
instead of opening and binding a new socket.  This provides a way to
2050
run, in a non-privileged process, a server that normally needs a
2051
reserved port number.
2052
 
2053
@item sort
2054
Used in @code{ls}.
2055
 
2056
@item source
2057
@samp{-W source} in @code{gawk}.
2058
 
2059
@item sparse
2060
@samp{-S} in @code{tar}.
2061
 
2062
@item speed-large-files
2063
@samp{-H} in @code{diff}.
2064
 
2065
@item split-at
2066
@samp{-E} in @code{unshar}.
2067
 
2068
@item split-size-limit
2069
@samp{-L} in @code{shar}.
2070
 
2071
@item squeeze-blank
2072
@samp{-s} in @code{cat}.
2073
 
2074
@item start-delete
2075
@samp{-w} in @code{wdiff}.
2076
 
2077
@item start-insert
2078
@samp{-y} in @code{wdiff}.
2079
 
2080
@item starting-file
2081
Used in @code{tar} and @code{diff} to specify which file within
2082
a directory to start processing with.
2083
 
2084
@item statistics
2085
@samp{-s} in @code{wdiff}.
2086
 
2087
@item stdin-file-list
2088
@samp{-S} in @code{shar}.
2089
 
2090
@item stop
2091
@samp{-S} in @code{make}.
2092
 
2093
@item strict
2094
@samp{-s} in @code{recode}.
2095
 
2096
@item strip
2097
@samp{-s} in @code{install}.
2098
 
2099
@item strip-all
2100
@samp{-s} in @code{strip}.
2101
 
2102
@item strip-debug
2103
@samp{-S} in @code{strip}.
2104
 
2105
@item submitter
2106
@samp{-s} in @code{shar}.
2107
 
2108
@item suffix
2109
@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
2110
 
2111
@item suffix-format
2112
@samp{-b} in @code{csplit}.
2113
 
2114
@item sum
2115
@samp{-s} in @code{gprof}.
2116
 
2117
@item summarize
2118
@samp{-s} in @code{du}.
2119
 
2120
@item symbolic
2121
@samp{-s} in @code{ln}.
2122
 
2123
@item symbols
2124
Used in GDB and @code{objdump}.
2125
 
2126
@item synclines
2127
@samp{-s} in @code{m4}.
2128
 
2129
@item sysname
2130
@samp{-s} in @code{uname}.
2131
 
2132
@item tabs
2133
@samp{-t} in @code{expand} and @code{unexpand}.
2134
 
2135
@item tabsize
2136
@samp{-T} in @code{ls}.
2137
 
2138
@item terminal
2139
@samp{-T} in @code{tput} and @code{ul}.
2140
@samp{-t} in @code{wdiff}.
2141
 
2142
@item text
2143
@samp{-a} in @code{diff}.
2144
 
2145
@item text-files
2146
@samp{-T} in @code{shar}.
2147
 
2148
@item time
2149
Used in @code{ls} and @code{touch}.
2150
 
2151
@item timeout
2152
Specify how long to wait before giving up on some operation.
2153
 
2154
@item to-stdout
2155
@samp{-O} in @code{tar}.
2156
 
2157
@item total
2158
@samp{-c} in @code{du}.
2159
 
2160
@item touch
2161
@samp{-t} in @code{make}, @code{ranlib}, and @code{recode}.
2162
 
2163
@item trace
2164
@samp{-t} in @code{m4}.
2165
 
2166
@item traditional
2167
@samp{-t} in @code{hello};
2168
@samp{-W traditional} in @code{gawk};
2169
@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
2170
 
2171
@item tty
2172
Used in GDB.
2173
 
2174
@item typedefs
2175
@samp{-t} in @code{ctags}.
2176
 
2177
@item typedefs-and-c++
2178
@samp{-T} in @code{ctags}.
2179
 
2180
@item typeset-mode
2181
@samp{-t} in @code{ptx}.
2182
 
2183
@item uncompress
2184
@samp{-z} in @code{tar}.
2185
 
2186
@item unconditional
2187
@samp{-u} in @code{cpio}.
2188
 
2189
@item undefine
2190
@samp{-U} in @code{m4}.
2191
 
2192
@item undefined-only
2193
@samp{-u} in @code{nm}.
2194
 
2195
@item update
2196
@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
2197
 
2198
@item usage
2199
Used in @code{gawk}; same as @samp{--help}.
2200
 
2201
@item uuencode
2202
@samp{-B} in @code{shar}.
2203
 
2204
@item vanilla-operation
2205
@samp{-V} in @code{shar}.
2206
 
2207
@item verbose
2208
Print more information about progress.  Many programs support this.
2209
 
2210
@item verify
2211
@samp{-W} in @code{tar}.
2212
 
2213
@item version
2214
Print the version number.
2215
 
2216
@item version-control
2217
@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
2218
 
2219
@item vgrind
2220
@samp{-v} in @code{ctags}.
2221
 
2222
@item volume
2223
@samp{-V} in @code{tar}.
2224
 
2225
@item what-if
2226
@samp{-W} in @code{make}.
2227
 
2228
@item whole-size-limit
2229
@samp{-l} in @code{shar}.
2230
 
2231
@item width
2232
@samp{-w} in @code{ls} and @code{ptx}.
2233
 
2234
@item word-regexp
2235
@samp{-W} in @code{ptx}.
2236
 
2237
@item writable
2238
@samp{-T} in @code{who}.
2239
 
2240
@item zeros
2241
@samp{-z} in @code{gprof}.
2242
@end table
2243
 
2244
@node OID Allocations
2245
@section OID Allocations
2246
@cindex OID allocations for GNU
2247
@cindex SNMP
2248
@cindex LDAP
2249
@cindex X.509
2250
 
2251
The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
2252
GNU Project (thanks to Werner Koch).  These are used for SNMP, LDAP,
2253
X.509 certificates, and so on.  The web site
2254
@url{http://www.alvestrand.no/objectid} has a (voluntary) listing of
2255
many OID assignments.
2256
 
2257
If you need a new slot for your GNU package, write
2258
@email{maintainers@@gnu.org}.  Here is a list of arcs currently
2259
assigned:
2260
 
2261
@example
2262
@include gnu-oids.texi
2263
@end example
2264
 
2265
 
2266
@node Memory Usage
2267
@section Memory Usage
2268
@cindex memory usage
2269
 
2270
If a program typically uses just a few meg of memory, don't bother making any
2271
effort to reduce memory usage.  For example, if it is impractical for
2272
other reasons to operate on files more than a few meg long, it is
2273
reasonable to read entire input files into memory to operate on them.
2274
 
2275
However, for programs such as @code{cat} or @code{tail}, that can
2276
usefully operate on very large files, it is important to avoid using a
2277
technique that would artificially limit the size of files it can handle.
2278
If a program works by lines and could be applied to arbitrary
2279
user-supplied input files, it should keep only a line in memory, because
2280
this is not very hard and users will want to be able to operate on input
2281
files that are bigger than will fit in memory all at once.
2282
 
2283
If your program creates complicated data structures, just make them in
2284
memory and give a fatal error if @code{malloc} returns zero.
2285
 
2286
@node File Usage
2287
@section File Usage
2288
@cindex file usage
2289
 
2290
Programs should be prepared to operate when @file{/usr} and @file{/etc}
2291
are read-only file systems.  Thus, if the program manages log files,
2292
lock files, backup files, score files, or any other files which are
2293
modified for internal purposes, these files should not be stored in
2294
@file{/usr} or @file{/etc}.
2295
 
2296
There are two exceptions.  @file{/etc} is used to store system
2297
configuration information; it is reasonable for a program to modify
2298
files in @file{/etc} when its job is to update the system configuration.
2299
Also, if the user explicitly asks to modify one file in a directory, it
2300
is reasonable for the program to store other files in the same
2301
directory.
2302
 
2303
@node Writing C
2304
@chapter Making The Best Use of C
2305
 
2306
This chapter provides advice on how best to use the C language
2307
when writing GNU software.
2308
 
2309
@menu
2310
* Formatting::                  Formatting your source code.
2311
* Comments::                    Commenting your work.
2312
* Syntactic Conventions::       Clean use of C constructs.
2313
* Names::                       Naming variables, functions, and files.
2314
* System Portability::          Portability among different operating systems.
2315
* CPU Portability::             Supporting the range of CPU types.
2316
* System Functions::            Portability and ``standard'' library functions.
2317
* Internationalization::        Techniques for internationalization.
2318
* Character Set::               Use ASCII by default.
2319
* Quote Characters::            Use `...' in the C locale.
2320
* Mmap::                        How you can safely use @code{mmap}.
2321
@end menu
2322
 
2323
@node Formatting
2324
@section Formatting Your Source Code
2325
@cindex formatting source code
2326
 
2327
@cindex open brace
2328
@cindex braces, in C source
2329
It is important to put the open-brace that starts the body of a C
2330
function in column one, so that they will start a defun.  Several
2331
tools look for open-braces in column one to find the beginnings of C
2332
functions.  These tools will not work on code not formatted that way.
2333
 
2334
Avoid putting open-brace, open-parenthesis or open-bracket in column
2335
one when they are inside a function, so that they won't start a defun.
2336
The open-brace that starts a @code{struct} body can go in column one
2337
if you find it useful to treat that definition as a defun.
2338
 
2339
It is also important for function definitions to start the name of the
2340
function in column one.  This helps people to search for function
2341
definitions, and may also help certain tools recognize them.  Thus,
2342
using Standard C syntax, the format is this:
2343
 
2344
@example
2345
static char *
2346
concat (char *s1, char *s2)
2347
@{
2348
  @dots{}
2349
@}
2350
@end example
2351
 
2352
@noindent
2353
or, if you want to use traditional C syntax, format the definition like
2354
this:
2355
 
2356
@example
2357
static char *
2358
concat (s1, s2)        /* Name starts in column one here */
2359
     char *s1, *s2;
2360
@{                     /* Open brace in column one here */
2361
  @dots{}
2362
@}
2363
@end example
2364
 
2365
In Standard C, if the arguments don't fit nicely on one line,
2366
split it like this:
2367
 
2368
@example
2369
int
2370
lots_of_args (int an_integer, long a_long, short a_short,
2371
              double a_double, float a_float)
2372
@dots{}
2373
@end example
2374
 
2375
The rest of this section gives our recommendations for other aspects of
2376
C formatting style, which is also the default style of the @code{indent}
2377
program in version 1.2 and newer.  It corresponds to the options
2378
 
2379
@smallexample
2380
-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2381
-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2382
@end smallexample
2383
 
2384
We don't think of these recommendations as requirements, because it
2385
causes no problems for users if two different programs have different
2386
formatting styles.
2387
 
2388
But whatever style you use, please use it consistently, since a mixture
2389
of styles within one program tends to look ugly.  If you are
2390
contributing changes to an existing program, please follow the style of
2391
that program.
2392
 
2393
For the body of the function, our recommended style looks like this:
2394
 
2395
@example
2396
if (x < foo (y, z))
2397
  haha = bar[4] + 5;
2398
else
2399
  @{
2400
    while (z)
2401
      @{
2402
        haha += foo (z, z);
2403
        z--;
2404
      @}
2405
    return ++x + bar ();
2406
  @}
2407
@end example
2408
 
2409
@cindex spaces before open-paren
2410
We find it easier to read a program when it has spaces before the
2411
open-parentheses and after the commas.  Especially after the commas.
2412
 
2413
When you split an expression into multiple lines, split it
2414
before an operator, not after one.  Here is the right way:
2415
 
2416
@cindex expressions, splitting
2417
@example
2418
if (foo_this_is_long && bar > win (x, y, z)
2419
    && remaining_condition)
2420
@end example
2421
 
2422
Try to avoid having two operators of different precedence at the same
2423
level of indentation.  For example, don't write this:
2424
 
2425
@example
2426
mode = (inmode[j] == VOIDmode
2427
        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2428
        ? outmode[j] : inmode[j]);
2429
@end example
2430
 
2431
Instead, use extra parentheses so that the indentation shows the nesting:
2432
 
2433
@example
2434
mode = ((inmode[j] == VOIDmode
2435
         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2436
        ? outmode[j] : inmode[j]);
2437
@end example
2438
 
2439
Insert extra parentheses so that Emacs will indent the code properly.
2440
For example, the following indentation looks nice if you do it by hand,
2441
 
2442
@example
2443
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2444
    + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2445
@end example
2446
 
2447
@noindent
2448
but Emacs would alter it.  Adding a set of parentheses produces
2449
something that looks equally nice, and which Emacs will preserve:
2450
 
2451
@example
2452
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2453
     + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2454
@end example
2455
 
2456
Format do-while statements like this:
2457
 
2458
@example
2459
do
2460
  @{
2461
    a = foo (a);
2462
  @}
2463
while (a > 0);
2464
@end example
2465
 
2466
@cindex formfeed
2467
@cindex control-L
2468
Please use formfeed characters (control-L) to divide the program into
2469
pages at logical places (but not within a function).  It does not matter
2470
just how long the pages are, since they do not have to fit on a printed
2471
page.  The formfeeds should appear alone on lines by themselves.
2472
 
2473
@node Comments
2474
@section Commenting Your Work
2475
@cindex commenting
2476
 
2477
Every program should start with a comment saying briefly what it is for.
2478
Example: @samp{fmt - filter for simple filling of text}.  This comment
2479
should be at the top of the source file containing the @samp{main}
2480
function of the program.
2481
 
2482
Also, please write a brief comment at the start of each source file,
2483
with the file name and a line or two about the overall purpose of the
2484
file.
2485
 
2486
Please write the comments in a GNU program in English, because English
2487
is the one language that nearly all programmers in all countries can
2488
read.  If you do not write English well, please write comments in
2489
English as well as you can, then ask other people to help rewrite them.
2490
If you can't write comments in English, please find someone to work with
2491
you and translate your comments into English.
2492
 
2493
Please put a comment on each function saying what the function does,
2494
what sorts of arguments it gets, and what the possible values of
2495
arguments mean and are used for.  It is not necessary to duplicate in
2496
words the meaning of the C argument declarations, if a C type is being
2497
used in its customary fashion.  If there is anything nonstandard about
2498
its use (such as an argument of type @code{char *} which is really the
2499
address of the second character of a string, not the first), or any
2500
possible values that would not work the way one would expect (such as,
2501
that strings containing newlines are not guaranteed to work), be sure
2502
to say so.
2503
 
2504
Also explain the significance of the return value, if there is one.
2505
 
2506
Please put two spaces after the end of a sentence in your comments, so
2507
that the Emacs sentence commands will work.  Also, please write
2508
complete sentences and capitalize the first word.  If a lower-case
2509
identifier comes at the beginning of a sentence, don't capitalize it!
2510
Changing the spelling makes it a different identifier.  If you don't
2511
like starting a sentence with a lower case letter, write the sentence
2512
differently (e.g., ``The identifier lower-case is @dots{}'').
2513
 
2514
The comment on a function is much clearer if you use the argument
2515
names to speak about the argument values.  The variable name itself
2516
should be lower case, but write it in upper case when you are speaking
2517
about the value rather than the variable itself.  Thus, ``the inode
2518
number NODE_NUM'' rather than ``an inode''.
2519
 
2520
There is usually no purpose in restating the name of the function in
2521
the comment before it, because the reader can see that for himself.
2522
There might be an exception when the comment is so long that the function
2523
itself would be off the bottom of the screen.
2524
 
2525
There should be a comment on each static variable as well, like this:
2526
 
2527
@example
2528
/* Nonzero means truncate lines in the display;
2529
   zero means continue them.  */
2530
int truncate_lines;
2531
@end example
2532
 
2533
@cindex conditionals, comments for
2534
@cindex @code{#endif}, commenting
2535
Every @samp{#endif} should have a comment, except in the case of short
2536
conditionals (just a few lines) that are not nested.  The comment should
2537
state the condition of the conditional that is ending, @emph{including
2538
its sense}.  @samp{#else} should have a comment describing the condition
2539
@emph{and sense} of the code that follows.  For example:
2540
 
2541
@example
2542
@group
2543
#ifdef foo
2544
  @dots{}
2545
#else /* not foo */
2546
  @dots{}
2547
#endif /* not foo */
2548
@end group
2549
@group
2550
#ifdef foo
2551
  @dots{}
2552
#endif /* foo */
2553
@end group
2554
@end example
2555
 
2556
@noindent
2557
but, by contrast, write the comments this way for a @samp{#ifndef}:
2558
 
2559
@example
2560
@group
2561
#ifndef foo
2562
  @dots{}
2563
#else /* foo */
2564
  @dots{}
2565
#endif /* foo */
2566
@end group
2567
@group
2568
#ifndef foo
2569
  @dots{}
2570
#endif /* not foo */
2571
@end group
2572
@end example
2573
 
2574
@node Syntactic Conventions
2575
@section Clean Use of C Constructs
2576
@cindex syntactic conventions
2577
 
2578
@cindex implicit @code{int}
2579
@cindex function argument, declaring
2580
Please explicitly declare the types of all objects.  For example, you
2581
should explicitly declare all arguments to functions, and you should
2582
declare functions to return @code{int} rather than omitting the
2583
@code{int}.
2584
 
2585
@cindex compiler warnings
2586
@cindex @samp{-Wall} compiler option
2587
Some programmers like to use the GCC @samp{-Wall} option, and change the
2588
code whenever it issues a warning.  If you want to do this, then do.
2589
Other programmers prefer not to use @samp{-Wall}, because it gives
2590
warnings for valid and legitimate code which they do not want to change.
2591
If you want to do this, then do.  The compiler should be your servant,
2592
not your master.
2593
 
2594
Declarations of external functions and functions to appear later in the
2595
source file should all go in one place near the beginning of the file
2596
(somewhere before the first function definition in the file), or else
2597
should go in a header file.  Don't put @code{extern} declarations inside
2598
functions.
2599
 
2600
@cindex temporary variables
2601
It used to be common practice to use the same local variables (with
2602
names like @code{tem}) over and over for different values within one
2603
function.  Instead of doing this, it is better to declare a separate local
2604
variable for each distinct purpose, and give it a name which is
2605
meaningful.  This not only makes programs easier to understand, it also
2606
facilitates optimization by good compilers.  You can also move the
2607
declaration of each local variable into the smallest scope that includes
2608
all its uses.  This makes the program even cleaner.
2609
 
2610
Don't use local variables or parameters that shadow global identifiers.
2611
 
2612
@cindex multiple variables in a line
2613
Don't declare multiple variables in one declaration that spans lines.
2614
Start a new declaration on each line, instead.  For example, instead
2615
of this:
2616
 
2617
@example
2618
@group
2619
int    foo,
2620
       bar;
2621
@end group
2622
@end example
2623
 
2624
@noindent
2625
write either this:
2626
 
2627
@example
2628
int foo, bar;
2629
@end example
2630
 
2631
@noindent
2632
or this:
2633
 
2634
@example
2635
int foo;
2636
int bar;
2637
@end example
2638
 
2639
@noindent
2640
(If they are global variables, each should have a comment preceding it
2641
anyway.)
2642
 
2643
When you have an @code{if}-@code{else} statement nested in another
2644
@code{if} statement, always put braces around the @code{if}-@code{else}.
2645
Thus, never write like this:
2646
 
2647
@example
2648
if (foo)
2649
  if (bar)
2650
    win ();
2651
  else
2652
    lose ();
2653
@end example
2654
 
2655
@noindent
2656
always like this:
2657
 
2658
@example
2659
if (foo)
2660
  @{
2661
    if (bar)
2662
      win ();
2663
    else
2664
      lose ();
2665
  @}
2666
@end example
2667
 
2668
If you have an @code{if} statement nested inside of an @code{else}
2669
statement, either write @code{else if} on one line, like this,
2670
 
2671
@example
2672
if (foo)
2673
  @dots{}
2674
else if (bar)
2675
  @dots{}
2676
@end example
2677
 
2678
@noindent
2679
with its @code{then}-part indented like the preceding @code{then}-part,
2680
or write the nested @code{if} within braces like this:
2681
 
2682
@example
2683
if (foo)
2684
  @dots{}
2685
else
2686
  @{
2687
    if (bar)
2688
      @dots{}
2689
  @}
2690
@end example
2691
 
2692
Don't declare both a structure tag and variables or typedefs in the
2693
same declaration.  Instead, declare the structure tag separately
2694
and then use it to declare the variables or typedefs.
2695
 
2696
Try to avoid assignments inside @code{if}-conditions (assignments
2697
inside @code{while}-conditions are ok).  For example, don't write
2698
this:
2699
 
2700
@example
2701
if ((foo = (char *) malloc (sizeof *foo)) == 0)
2702
  fatal ("virtual memory exhausted");
2703
@end example
2704
 
2705
@noindent
2706
instead, write this:
2707
 
2708
@example
2709
foo = (char *) malloc (sizeof *foo);
2710
if (foo == 0)
2711
  fatal ("virtual memory exhausted");
2712
@end example
2713
 
2714
@pindex lint
2715
Don't make the program ugly to placate @code{lint}.  Please don't insert any
2716
casts to @code{void}.  Zero without a cast is perfectly fine as a null
2717
pointer constant, except when calling a varargs function.
2718
 
2719
@node Names
2720
@section Naming Variables, Functions, and Files
2721
 
2722
@cindex names of variables, functions, and files
2723
The names of global variables and functions in a program serve as
2724
comments of a sort.  So don't choose terse names---instead, look for
2725
names that give useful information about the meaning of the variable or
2726
function.  In a GNU program, names should be English, like other
2727
comments.
2728
 
2729
Local variable names can be shorter, because they are used only within
2730
one context, where (presumably) comments explain their purpose.
2731
 
2732
Try to limit your use of abbreviations in symbol names.  It is ok to
2733
make a few abbreviations, explain what they mean, and then use them
2734
frequently, but don't use lots of obscure abbreviations.
2735
 
2736
Please use underscores to separate words in a name, so that the Emacs
2737
word commands can be useful within them.  Stick to lower case; reserve
2738
upper case for macros and @code{enum} constants, and for name-prefixes
2739
that follow a uniform convention.
2740
 
2741
For example, you should use names like @code{ignore_space_change_flag};
2742
don't use names like @code{iCantReadThis}.
2743
 
2744
Variables that indicate whether command-line options have been
2745
specified should be named after the meaning of the option, not after
2746
the option-letter.  A comment should state both the exact meaning of
2747
the option and its letter.  For example,
2748
 
2749
@example
2750
@group
2751
/* Ignore changes in horizontal whitespace (-b).  */
2752
int ignore_space_change_flag;
2753
@end group
2754
@end example
2755
 
2756
When you want to define names with constant integer values, use
2757
@code{enum} rather than @samp{#define}.  GDB knows about enumeration
2758
constants.
2759
 
2760
@cindex file-name limitations
2761
@pindex doschk
2762
You might want to make sure that none of the file names would conflict
2763
if the files were loaded onto an MS-DOS file system which shortens the
2764
names.  You can use the program @code{doschk} to test for this.
2765
 
2766
Some GNU programs were designed to limit themselves to file names of 14
2767
characters or less, to avoid file name conflicts if they are read into
2768
older System V systems.  Please preserve this feature in the existing
2769
GNU programs that have it, but there is no need to do this in new GNU
2770
programs.  @code{doschk} also reports file names longer than 14
2771
characters.
2772
 
2773
@node System Portability
2774
@section Portability between System Types
2775
@cindex portability, between system types
2776
 
2777
In the Unix world, ``portability'' refers to porting to different Unix
2778
versions.  For a GNU program, this kind of portability is desirable, but
2779
not paramount.
2780
 
2781
The primary purpose of GNU software is to run on top of the GNU kernel,
2782
compiled with the GNU C compiler, on various types of @sc{cpu}.  So the
2783
kinds of portability that are absolutely necessary are quite limited.
2784
But it is important to support Linux-based GNU systems, since they
2785
are the form of GNU that is popular.
2786
 
2787
Beyond that, it is good to support the other free operating systems
2788
(*BSD), and it is nice to support other Unix-like systems if you want
2789
to.  Supporting a variety of Unix-like systems is desirable, although
2790
not paramount.  It is usually not too hard, so you may as well do it.
2791
But you don't have to consider it an obligation, if it does turn out to
2792
be hard.
2793
 
2794
@pindex autoconf
2795
The easiest way to achieve portability to most Unix-like systems is to
2796
use Autoconf.  It's unlikely that your program needs to know more
2797
information about the host platform than Autoconf can provide, simply
2798
because most of the programs that need such knowledge have already been
2799
written.
2800
 
2801
Avoid using the format of semi-internal data bases (e.g., directories)
2802
when there is a higher-level alternative (@code{readdir}).
2803
 
2804
@cindex non-@sc{posix} systems, and portability
2805
As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
2806
and older Macintosh systems, supporting them is often a lot of work.
2807
When that is the case, it is better to spend your time adding features
2808
that will be useful on GNU and GNU/Linux, rather than on supporting
2809
other incompatible systems.
2810
 
2811
If you do support Windows, please do not abbreviate it as ``win''.  In
2812
hacker terminology, calling something a ``win'' is a form of praise.
2813
You're free to praise Microsoft Windows on your own if you want, but
2814
please don't do this in GNU packages.  Instead of abbreviating
2815
``Windows'' to ``win'', you can write it in full or abbreviate it to
2816
``woe'' or ``w''.  In GNU Emacs, for instance, we use @samp{w32} in
2817
file names of Windows-specific files, but the macro for Windows
2818
conditionals is called @code{WINDOWSNT}.
2819
 
2820
It is a good idea to define the ``feature test macro''
2821
@code{_GNU_SOURCE} when compiling your C files.  When you compile on GNU
2822
or GNU/Linux, this will enable the declarations of GNU library extension
2823
functions, and that will usually give you a compiler error message if
2824
you define the same function names in some other way in your program.
2825
(You don't have to actually @emph{use} these functions, if you prefer
2826
to make the program more portable to other systems.)
2827
 
2828
But whether or not you use these GNU extensions, you should avoid
2829
using their names for any other meanings.  Doing so would make it hard
2830
to move your code into other GNU programs.
2831
 
2832
@node CPU Portability
2833
@section Portability between @sc{cpu}s
2834
 
2835
@cindex data types, and portability
2836
@cindex portability, and data types
2837
Even GNU systems will differ because of differences among @sc{cpu}
2838
types---for example, difference in byte ordering and alignment
2839
requirements.  It is absolutely essential to handle these differences.
2840
However, don't make any effort to cater to the possibility that an
2841
@code{int} will be less than 32 bits.  We don't support 16-bit machines
2842
in GNU.
2843
 
2844
Similarly, don't make any effort to cater to the possibility that
2845
@code{long} will be smaller than predefined types like @code{size_t}.
2846
For example, the following code is ok:
2847
 
2848
@example
2849
printf ("size = %lu\n", (unsigned long) sizeof array);
2850
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2851
@end example
2852
 
2853
1989 Standard C requires this to work, and we know of only one
2854
counterexample: 64-bit programs on Microsoft Windows.  We will
2855
leave it to those who want to port GNU programs to that environment
2856
to figure out how to do it.
2857
 
2858
Predefined file-size types like @code{off_t} are an exception: they are
2859
longer than @code{long} on many platforms, so code like the above won't
2860
work with them.  One way to print an @code{off_t} value portably is to
2861
print its digits yourself, one by one.
2862
 
2863
Don't assume that the address of an @code{int} object is also the
2864
address of its least-significant byte.  This is false on big-endian
2865
machines.  Thus, don't make the following mistake:
2866
 
2867
@example
2868
int c;
2869
@dots{}
2870
while ((c = getchar ()) != EOF)
2871
  write (file_descriptor, &c, 1);
2872
@end example
2873
 
2874
@noindent Instead, use @code{unsigned char} as follows.  (The @code{unsigned}
2875
is for portability to unusual systems where @code{char} is signed and
2876
where there is integer overflow checking.)
2877
 
2878
@example
2879
int c;
2880
while ((c = getchar ()) != EOF)
2881
  @{
2882
    unsigned char u = c;
2883
    write (file_descriptor, &u, 1);
2884
  @}
2885
@end example
2886
 
2887
It used to be ok to not worry about the difference between pointers
2888
and integers when passing arguments to functions.  However, on most
2889
modern 64-bit machines pointers are wider than @code{int}.
2890
Conversely, integer types like @code{long long int} and @code{off_t}
2891
are wider than pointers on most modern 32-bit machines.  Hence it's
2892
often better nowadays to use prototypes to define functions whose
2893
argument types are not trivial.
2894
 
2895
In particular, if functions accept varying argument counts or types
2896
they should be declared using prototypes containing @samp{...} and
2897
defined using @file{stdarg.h}.  For an example of this, please see the
2898
@uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
2899
declares and defines the following function:
2900
 
2901
@example
2902
/* Print a message with `fprintf (stderr, FORMAT, ...)';
2903
   if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2904
   If STATUS is nonzero, terminate the program with `exit (STATUS)'.  */
2905
 
2906
void error (int status, int errnum, const char *format, ...);
2907
@end example
2908
 
2909
A simple way to use the Gnulib error module is to obtain the two
2910
source files @file{error.c} and @file{error.h} from the Gnulib library
2911
source code repository at
2912
@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=gnulib.git}.
2913
Here's a sample use:
2914
 
2915
@example
2916
#include "error.h"
2917
#include <errno.h>
2918
#include <stdio.h>
2919
 
2920
char *program_name = "myprogram";
2921
 
2922
FILE *
2923
xfopen (char const *name)
2924
@{
2925
  FILE *fp = fopen (name, "r");
2926
  if (! fp)
2927
    error (1, errno, "cannot read %s", name);
2928
  return fp;
2929
@}
2930
@end example
2931
 
2932
@cindex casting pointers to integers
2933
Avoid casting pointers to integers if you can.  Such casts greatly
2934
reduce portability, and in most programs they are easy to avoid.  In the
2935
cases where casting pointers to integers is essential---such as, a Lisp
2936
interpreter which stores type information as well as an address in one
2937
word---you'll have to make explicit provisions to handle different word
2938
sizes.  You will also need to make provision for systems in which the
2939
normal range of addresses you can get from @code{malloc} starts far away
2940
from zero.
2941
 
2942
@node System Functions
2943
@section Calling System Functions
2944
@cindex library functions, and portability
2945
@cindex portability, and library functions
2946
 
2947
C implementations differ substantially.  Standard C reduces but does
2948
not eliminate the incompatibilities; meanwhile, many GNU packages still
2949
support pre-standard compilers because this is not hard to do.  This
2950
chapter gives recommendations for how to use the more-or-less standard C
2951
library functions to avoid unnecessary loss of portability.
2952
 
2953
@itemize @bullet
2954
@item
2955
Don't use the return value of @code{sprintf}.  It returns the number of
2956
characters written on some systems, but not on all systems.
2957
 
2958
@item
2959
Be aware that @code{vfprintf} is not always available.
2960
 
2961
@item
2962
@code{main} should be declared to return type @code{int}.  It should
2963
terminate either by calling @code{exit} or by returning the integer
2964
status code; make sure it cannot ever return an undefined value.
2965
 
2966
@cindex declaration for system functions
2967
@item
2968
Don't declare system functions explicitly.
2969
 
2970
Almost any declaration for a system function is wrong on some system.
2971
To minimize conflicts, leave it to the system header files to declare
2972
system functions.  If the headers don't declare a function, let it
2973
remain undeclared.
2974
 
2975
While it may seem unclean to use a function without declaring it, in
2976
practice this works fine for most system library functions on the
2977
systems where this really happens; thus, the disadvantage is only
2978
theoretical.  By contrast, actual declarations have frequently caused
2979
actual conflicts.
2980
 
2981
@item
2982
If you must declare a system function, don't specify the argument types.
2983
Use an old-style declaration, not a Standard C prototype.  The more you
2984
specify about the function, the more likely a conflict.
2985
 
2986
@item
2987
In particular, don't unconditionally declare @code{malloc} or
2988
@code{realloc}.
2989
 
2990
Most GNU programs use those functions just once, in functions
2991
conventionally named @code{xmalloc} and @code{xrealloc}.  These
2992
functions call @code{malloc} and @code{realloc}, respectively, and
2993
check the results.
2994
 
2995
Because @code{xmalloc} and @code{xrealloc} are defined in your program,
2996
you can declare them in other files without any risk of type conflict.
2997
 
2998
On most systems, @code{int} is the same length as a pointer; thus, the
2999
calls to @code{malloc} and @code{realloc} work fine.  For the few
3000
exceptional systems (mostly 64-bit machines), you can use
3001
@strong{conditionalized} declarations of @code{malloc} and
3002
@code{realloc}---or put these declarations in configuration files
3003
specific to those systems.
3004
 
3005
@cindex string library functions
3006
@item
3007
The string functions require special treatment.  Some Unix systems have
3008
a header file @file{string.h}; others have @file{strings.h}.  Neither
3009
file name is portable.  There are two things you can do: use Autoconf to
3010
figure out which file to include, or don't include either file.
3011
 
3012
@item
3013
If you don't include either strings file, you can't get declarations for
3014
the string functions from the header file in the usual way.
3015
 
3016
That causes less of a problem than you might think.  The newer standard
3017
string functions should be avoided anyway because many systems still
3018
don't support them.  The string functions you can use are these:
3019
 
3020
@example
3021
strcpy   strncpy   strcat   strncat
3022
strlen   strcmp    strncmp
3023
strchr   strrchr
3024
@end example
3025
 
3026
The copy and concatenate functions work fine without a declaration as
3027
long as you don't use their values.  Using their values without a
3028
declaration fails on systems where the width of a pointer differs from
3029
the width of @code{int}, and perhaps in other cases.  It is trivial to
3030
avoid using their values, so do that.
3031
 
3032
The compare functions and @code{strlen} work fine without a declaration
3033
on most systems, possibly all the ones that GNU software runs on.
3034
You may find it necessary to declare them @strong{conditionally} on a
3035
few systems.
3036
 
3037
The search functions must be declared to return @code{char *}.  Luckily,
3038
there is no variation in the data type they return.  But there is
3039
variation in their names.  Some systems give these functions the names
3040
@code{index} and @code{rindex}; other systems use the names
3041
@code{strchr} and @code{strrchr}.  Some systems support both pairs of
3042
names, but neither pair works on all systems.
3043
 
3044
You should pick a single pair of names and use it throughout your
3045
program.  (Nowadays, it is better to choose @code{strchr} and
3046
@code{strrchr} for new programs, since those are the standard
3047
names.)  Declare both of those names as functions returning @code{char
3048
*}.  On systems which don't support those names, define them as macros
3049
in terms of the other pair.  For example, here is what to put at the
3050
beginning of your file (or in a header) if you want to use the names
3051
@code{strchr} and @code{strrchr} throughout:
3052
 
3053
@example
3054
#ifndef HAVE_STRCHR
3055
#define strchr index
3056
#endif
3057
#ifndef HAVE_STRRCHR
3058
#define strrchr rindex
3059
#endif
3060
 
3061
char *strchr ();
3062
char *strrchr ();
3063
@end example
3064
@end itemize
3065
 
3066
Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
3067
macros defined in systems where the corresponding functions exist.
3068
One way to get them properly defined is to use Autoconf.
3069
 
3070
@node Internationalization
3071
@section Internationalization
3072
@cindex internationalization
3073
 
3074
@pindex gettext
3075
GNU has a library called GNU gettext that makes it easy to translate the
3076
messages in a program into various languages.  You should use this
3077
library in every program.  Use English for the messages as they appear
3078
in the program, and let gettext provide the way to translate them into
3079
other languages.
3080
 
3081
Using GNU gettext involves putting a call to the @code{gettext} macro
3082
around each string that might need translation---like this:
3083
 
3084
@example
3085
printf (gettext ("Processing file `%s'..."));
3086
@end example
3087
 
3088
@noindent
3089
This permits GNU gettext to replace the string @code{"Processing file
3090
`%s'..."} with a translated version.
3091
 
3092
Once a program uses gettext, please make a point of writing calls to
3093
@code{gettext} when you add new strings that call for translation.
3094
 
3095
Using GNU gettext in a package involves specifying a @dfn{text domain
3096
name} for the package.  The text domain name is used to separate the
3097
translations for this package from the translations for other packages.
3098
Normally, the text domain name should be the same as the name of the
3099
package---for example, @samp{coreutils} for the GNU core utilities.
3100
 
3101
@cindex message text, and internationalization
3102
To enable gettext to work well, avoid writing code that makes
3103
assumptions about the structure of words or sentences.  When you want
3104
the precise text of a sentence to vary depending on the data, use two or
3105
more alternative string constants each containing a complete sentences,
3106
rather than inserting conditionalized words or phrases into a single
3107
sentence framework.
3108
 
3109
Here is an example of what not to do:
3110
 
3111
@smallexample
3112
printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
3113
@end smallexample
3114
 
3115
If you apply gettext to all strings, like this,
3116
 
3117
@smallexample
3118
printf (gettext ("%s is full"),
3119
        capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
3120
@end smallexample
3121
 
3122
@noindent
3123
the translator will hardly know that "disk" and "floppy disk" are meant to
3124
be substituted in the other string.  Worse, in some languages (like French)
3125
the construction will not work: the translation of the word "full" depends
3126
on the gender of the first part of the sentence; it happens to be not the
3127
same for "disk" as for "floppy disk".
3128
 
3129
Complete sentences can be translated without problems:
3130
 
3131
@example
3132
printf (capacity > 5000000 ? gettext ("disk is full")
3133
        : gettext ("floppy disk is full"));
3134
@end example
3135
 
3136
A similar problem appears at the level of sentence structure with this
3137
code:
3138
 
3139
@example
3140
printf ("#  Implicit rule search has%s been done.\n",
3141
        f->tried_implicit ? "" : " not");
3142
@end example
3143
 
3144
@noindent
3145
Adding @code{gettext} calls to this code cannot give correct results for
3146
all languages, because negation in some languages requires adding words
3147
at more than one place in the sentence.  By contrast, adding
3148
@code{gettext} calls does the job straightforwardly if the code starts
3149
out like this:
3150
 
3151
@example
3152
printf (f->tried_implicit
3153
        ? "#  Implicit rule search has been done.\n",
3154
        : "#  Implicit rule search has not been done.\n");
3155
@end example
3156
 
3157
Another example is this one:
3158
 
3159
@example
3160
printf ("%d file%s processed", nfiles,
3161
        nfiles != 1 ? "s" : "");
3162
@end example
3163
 
3164
@noindent
3165
The problem with this example is that it assumes that plurals are made
3166
by adding `s'.  If you apply gettext to the format string, like this,
3167
 
3168
@example
3169
printf (gettext ("%d file%s processed"), nfiles,
3170
        nfiles != 1 ? "s" : "");
3171
@end example
3172
 
3173
@noindent
3174
the message can use different words, but it will still be forced to use
3175
`s' for the plural.  Here is a better way, with gettext being applied to
3176
the two strings independently:
3177
 
3178
@example
3179
printf ((nfiles != 1 ? gettext ("%d files processed")
3180
         : gettext ("%d file processed")),
3181
        nfiles);
3182
@end example
3183
 
3184
@noindent
3185
But this still doesn't work for languages like Polish, which has three
3186
plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ...
3187
and one for the rest.  The GNU @code{ngettext} function solves this problem:
3188
 
3189
@example
3190
printf (ngettext ("%d files processed", "%d file processed", nfiles),
3191
        nfiles);
3192
@end example
3193
 
3194
 
3195
@node Character Set
3196
@section Character Set
3197
@cindex character set
3198
@cindex encodings
3199
@cindex ASCII characters
3200
@cindex non-ASCII characters
3201
 
3202
Sticking to the ASCII character set (plain text, 7-bit characters) is
3203
preferred in GNU source code comments, text documents, and other
3204
contexts, unless there is good reason to do something else because of
3205
the application domain.  For example, if source code deals with the
3206
French Revolutionary calendar, it is OK if its literal strings contain
3207
accented characters in month names like ``Flor@'eal''.  Also, it is OK
3208
to use non-ASCII characters to represent proper names of contributors in
3209
change logs (@pxref{Change Logs}).
3210
 
3211
If you need to use non-ASCII characters, you should normally stick with
3212
one encoding, as one cannot in general mix encodings reliably.
3213
 
3214
 
3215
@node Quote Characters
3216
@section Quote Characters
3217
@cindex quote characters
3218
@cindex locale-specific quote characters
3219
@cindex left quote
3220
@cindex grave accent
3221
 
3222
In the C locale, GNU programs should stick to plain ASCII for quotation
3223
characters in messages to users: preferably 0x60 (@samp{`}) for left
3224
quotes and 0x27 (@samp{'}) for right quotes.  It is ok, but not
3225
required, to use locale-specific quotes in other locales.
3226
 
3227
The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
3228
@code{quotearg} modules provide a reasonably straightforward way to
3229
support locale-specific quote characters, as well as taking care of
3230
other issues, such as quoting a filename that itself contains a quote
3231
character.  See the Gnulib documentation for usage details.
3232
 
3233
In any case, the documentation for your program should clearly specify
3234
how it does quoting, if different than the preferred method of @samp{`}
3235
and @samp{'}.  This is especially important if the output of your
3236
program is ever likely to be parsed by another program.
3237
 
3238
Quotation characters are a difficult area in the computing world at
3239
this time: there are no true left or right quote characters in Latin1;
3240
the @samp{`} character we use was standardized there as a grave
3241
accent.  Moreover, Latin1 is still not universally usable.
3242
 
3243
Unicode contains the unambiguous quote characters required, and its
3244
common encoding UTF-8 is upward compatible with Latin1.  However,
3245
Unicode and UTF-8 are not universally well-supported, either.
3246
 
3247
This may change over the next few years, and then we will revisit
3248
this.
3249
 
3250
 
3251
@node Mmap
3252
@section Mmap
3253
@findex mmap
3254
 
3255
Don't assume that @code{mmap} either works on all files or fails
3256
for all files.  It may work on some files and fail on others.
3257
 
3258
The proper way to use @code{mmap} is to try it on the specific file for
3259
which you want to use it---and if @code{mmap} doesn't work, fall back on
3260
doing the job in another way using @code{read} and @code{write}.
3261
 
3262
The reason this precaution is needed is that the GNU kernel (the HURD)
3263
provides a user-extensible file system, in which there can be many
3264
different kinds of ``ordinary files.''  Many of them support
3265
@code{mmap}, but some do not.  It is important to make programs handle
3266
all these kinds of files.
3267
 
3268
@node Documentation
3269
@chapter Documenting Programs
3270
@cindex documentation
3271
 
3272
A GNU program should ideally come with full free documentation, adequate
3273
for both reference and tutorial purposes.  If the package can be
3274
programmed or extended, the documentation should cover programming or
3275
extending it, as well as just using it.
3276
 
3277
@menu
3278
* GNU Manuals::                 Writing proper manuals.
3279
* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
3280
* Manual Structure Details::    Specific structure conventions.
3281
* License for Manuals::         Writing the distribution terms for a manual.
3282
* Manual Credits::              Giving credit to documentation contributors.
3283
* Printed Manuals::             Mentioning the printed manual.
3284
* NEWS File::                   NEWS files supplement manuals.
3285
* Change Logs::                 Recording changes.
3286
* Man Pages::                   Man pages are secondary.
3287
* Reading other Manuals::       How far you can go in learning
3288
                                from other manuals.
3289
@end menu
3290
 
3291
@node GNU Manuals
3292
@section GNU Manuals
3293
 
3294
The preferred document format for the GNU system is the Texinfo
3295
formatting language.  Every GNU package should (ideally) have
3296
documentation in Texinfo both for reference and for learners.  Texinfo
3297
makes it possible to produce a good quality formatted book, using
3298
@TeX{}, and to generate an Info file.  It is also possible to generate
3299
HTML output from Texinfo source.  See the Texinfo manual, either the
3300
hardcopy, or the on-line version available through @code{info} or the
3301
Emacs Info subsystem (@kbd{C-h i}).
3302
 
3303
Nowadays some other formats such as Docbook and Sgmltexi can be
3304
converted automatically into Texinfo.  It is ok to produce the Texinfo
3305
documentation by conversion this way, as long as it gives good results.
3306
 
3307
Make sure your manual is clear to a reader who knows nothing about the
3308
topic and reads it straight through.  This means covering basic topics
3309
at the beginning, and advanced topics only later.  This also means
3310
defining every specialized term when it is first used.
3311
 
3312
Programmers tend to carry over the structure of the program as the
3313
structure for its documentation.  But this structure is not
3314
necessarily good for explaining how to use the program; it may be
3315
irrelevant and confusing for a user.
3316
 
3317
Instead, the right way to structure documentation is according to the
3318
concepts and questions that a user will have in mind when reading it.
3319
This principle applies at every level, from the lowest (ordering
3320
sentences in a paragraph) to the highest (ordering of chapter topics
3321
within the manual).  Sometimes this structure of ideas matches the
3322
structure of the implementation of the software being documented---but
3323
often they are different.  An important part of learning to write good
3324
documentation is to learn to notice when you have unthinkingly
3325
structured the documentation like the implementation, stop yourself,
3326
and look for better alternatives.
3327
 
3328
For example, each program in the GNU system probably ought to be
3329
documented in one manual; but this does not mean each program should
3330
have its own manual.  That would be following the structure of the
3331
implementation, rather than the structure that helps the user
3332
understand.
3333
 
3334
Instead, each manual should cover a coherent @emph{topic}.  For example,
3335
instead of a manual for @code{diff} and a manual for @code{diff3}, we
3336
have one manual for ``comparison of files'' which covers both of those
3337
programs, as well as @code{cmp}.  By documenting these programs
3338
together, we can make the whole subject clearer.
3339
 
3340
The manual which discusses a program should certainly document all of
3341
the program's command-line options and all of its commands.  It should
3342
give examples of their use.  But don't organize the manual as a list
3343
of features.  Instead, organize it logically, by subtopics.  Address
3344
the questions that a user will ask when thinking about the job that
3345
the program does.  Don't just tell the reader what each feature can
3346
do---say what jobs it is good for, and show how to use it for those
3347
jobs.  Explain what is recommended usage, and what kinds of usage
3348
users should avoid.
3349
 
3350
In general, a GNU manual should serve both as tutorial and reference.
3351
It should be set up for convenient access to each topic through Info,
3352
and for reading straight through (appendixes aside).  A GNU manual
3353
should give a good introduction to a beginner reading through from the
3354
start, and should also provide all the details that hackers want.
3355
The Bison manual is a good example of this---please take a look at it
3356
to see what we mean.
3357
 
3358
That is not as hard as it first sounds.  Arrange each chapter as a
3359
logical breakdown of its topic, but order the sections, and write their
3360
text, so that reading the chapter straight through makes sense.  Do
3361
likewise when structuring the book into chapters, and when structuring a
3362
section into paragraphs.  The watchword is, @emph{at each point, address
3363
the most fundamental and important issue raised by the preceding text.}
3364
 
3365
If necessary, add extra chapters at the beginning of the manual which
3366
are purely tutorial and cover the basics of the subject.  These provide
3367
the framework for a beginner to understand the rest of the manual.  The
3368
Bison manual provides a good example of how to do this.
3369
 
3370
To serve as a reference, a manual should have an Index that list all the
3371
functions, variables, options, and important concepts that are part of
3372
the program.  One combined Index should do for a short manual, but
3373
sometimes for a complex package it is better to use multiple indices.
3374
The Texinfo manual includes advice on preparing good index entries, see
3375
@ref{Index Entries, , Making Index Entries, texinfo, GNU Texinfo}, and
3376
see @ref{Indexing Commands, , Defining the Entries of an
3377
Index, texinfo, GNU Texinfo}.
3378
 
3379
Don't use Unix man pages as a model for how to write GNU documentation;
3380
most of them are terse, badly structured, and give inadequate
3381
explanation of the underlying concepts.  (There are, of course, some
3382
exceptions.)  Also, Unix man pages use a particular format which is
3383
different from what we use in GNU manuals.
3384
 
3385
Please include an email address in the manual for where to report
3386
bugs @emph{in the text of the manual}.
3387
 
3388
Please do not use the term ``pathname'' that is used in Unix
3389
documentation; use ``file name'' (two words) instead.  We use the term
3390
``path'' only for search paths, which are lists of directory names.
3391
 
3392
Please do not use the term ``illegal'' to refer to erroneous input to
3393
a computer program.  Please use ``invalid'' for this, and reserve the
3394
term ``illegal'' for activities prohibited by law.
3395
 
3396
Please do not write @samp{()} after a function name just to indicate
3397
it is a function.  @code{foo ()} is not a function, it is a function
3398
call with no arguments.
3399
 
3400
@node Doc Strings and Manuals
3401
@section Doc Strings and Manuals
3402
 
3403
Some programming systems, such as Emacs, provide a documentation string
3404
for each function, command or variable.  You may be tempted to write a
3405
reference manual by compiling the documentation strings and writing a
3406
little additional text to go around them---but you must not do it.  That
3407
approach is a fundamental mistake.  The text of well-written
3408
documentation strings will be entirely wrong for a manual.
3409
 
3410
A documentation string needs to stand alone---when it appears on the
3411
screen, there will be no other text to introduce or explain it.
3412
Meanwhile, it can be rather informal in style.
3413
 
3414
The text describing a function or variable in a manual must not stand
3415
alone; it appears in the context of a section or subsection.  Other text
3416
at the beginning of the section should explain some of the concepts, and
3417
should often make some general points that apply to several functions or
3418
variables.  The previous descriptions of functions and variables in the
3419
section will also have given information about the topic.  A description
3420
written to stand alone would repeat some of that information; this
3421
redundancy looks bad.  Meanwhile, the informality that is acceptable in
3422
a documentation string is totally unacceptable in a manual.
3423
 
3424
The only good way to use documentation strings in writing a good manual
3425
is to use them as a source of information for writing good text.
3426
 
3427
@node Manual Structure Details
3428
@section Manual Structure Details
3429
@cindex manual structure
3430
 
3431
The title page of the manual should state the version of the programs or
3432
packages documented in the manual.  The Top node of the manual should
3433
also contain this information.  If the manual is changing more
3434
frequently than or independent of the program, also state a version
3435
number for the manual in both of these places.
3436
 
3437
Each program documented in the manual should have a node named
3438
@samp{@var{program} Invocation} or @samp{Invoking @var{program}}.  This
3439
node (together with its subnodes, if any) should describe the program's
3440
command line arguments and how to run it (the sort of information people
3441
would look for in a man page).  Start with an @samp{@@example}
3442
containing a template for all the options and arguments that the program
3443
uses.
3444
 
3445
Alternatively, put a menu item in some menu whose item name fits one of
3446
the above patterns.  This identifies the node which that item points to
3447
as the node for this purpose, regardless of the node's actual name.
3448
 
3449
The @samp{--usage} feature of the Info reader looks for such a node
3450
or menu item in order to find the relevant text, so it is essential
3451
for every Texinfo file to have one.
3452
 
3453
If one manual describes several programs, it should have such a node for
3454
each program described in the manual.
3455
 
3456
@node License for Manuals
3457
@section License for Manuals
3458
@cindex license for manuals
3459
 
3460
Please use the GNU Free Documentation License for all GNU manuals that
3461
are more than a few pages long.  Likewise for a collection of short
3462
documents---you only need one copy of the GNU FDL for the whole
3463
collection.  For a single short document, you can use a very permissive
3464
non-copyleft license, to avoid taking up space with a long license.
3465
 
3466
See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
3467
of how to employ the GFDL.
3468
 
3469
Note that it is not obligatory to include a copy of the GNU GPL or GNU
3470
LGPL in a manual whose license is neither the GPL nor the LGPL.  It can
3471
be a good idea to include the program's license in a large manual; in a
3472
short manual, whose size would be increased considerably by including
3473
the program's license, it is probably better not to include it.
3474
 
3475
@node Manual Credits
3476
@section Manual Credits
3477
@cindex credits for manuals
3478
 
3479
Please credit the principal human writers of the manual as the authors,
3480
on the title page of the manual.  If a company sponsored the work, thank
3481
the company in a suitable place in the manual, but do not cite the
3482
company as an author.
3483
 
3484
@node Printed Manuals
3485
@section Printed Manuals
3486
 
3487
The FSF publishes some GNU manuals in printed form.  To encourage sales
3488
of these manuals, the on-line versions of the manual should mention at
3489
the very start that the printed manual is available and should point at
3490
information for getting it---for instance, with a link to the page
3491
@url{http://www.gnu.org/order/order.html}.  This should not be included
3492
in the printed manual, though, because there it is redundant.
3493
 
3494
It is also useful to explain in the on-line forms of the manual how the
3495
user can print out the manual from the sources.
3496
 
3497
@node NEWS File
3498
@section The NEWS File
3499
@cindex @file{NEWS} file
3500
 
3501
In addition to its manual, the package should have a file named
3502
@file{NEWS} which contains a list of user-visible changes worth
3503
mentioning.  In each new release, add items to the front of the file and
3504
identify the version they pertain to.  Don't discard old items; leave
3505
them in the file after the newer items.  This way, a user upgrading from
3506
any previous version can see what is new.
3507
 
3508
If the @file{NEWS} file gets very long, move some of the older items
3509
into a file named @file{ONEWS} and put a note at the end referring the
3510
user to that file.
3511
 
3512
@node Change Logs
3513
@section Change Logs
3514
@cindex change logs
3515
 
3516
Keep a change log to describe all the changes made to program source
3517
files.  The purpose of this is so that people investigating bugs in the
3518
future will know about the changes that might have introduced the bug.
3519
Often a new bug can be found by looking at what was recently changed.
3520
More importantly, change logs can help you eliminate conceptual
3521
inconsistencies between different parts of a program, by giving you a
3522
history of how the conflicting concepts arose and who they came from.
3523
 
3524
@menu
3525
* Change Log Concepts::
3526
* Style of Change Logs::
3527
* Simple Changes::
3528
* Conditional Changes::
3529
* Indicating the Part Changed::
3530
@end menu
3531
 
3532
@node Change Log Concepts
3533
@subsection Change Log Concepts
3534
 
3535
You can think of the change log as a conceptual ``undo list'' which
3536
explains how earlier versions were different from the current version.
3537
People can see the current version; they don't need the change log
3538
to tell them what is in it.  What they want from a change log is a
3539
clear explanation of how the earlier version differed.
3540
 
3541
The change log file is normally called @file{ChangeLog} and covers an
3542
entire directory.  Each directory can have its own change log, or a
3543
directory can use the change log of its parent directory---it's up to
3544
you.
3545
 
3546
Another alternative is to record change log information with a version
3547
control system such as RCS or CVS.  This can be converted automatically
3548
to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
3549
@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
3550
 
3551
There's no need to describe the full purpose of the changes or how
3552
they work together.  However, sometimes it is useful to write one line
3553
to describe the overall purpose of a change or a batch of changes.  If
3554
you think that a change calls for explanation, you're probably right.
3555
Please do explain it---but please put the full explanation in comments
3556
in the code, where people will see it whenever they see the code.  For
3557
example, ``New function'' is enough for the change log when you add a
3558
function, because there should be a comment before the function
3559
definition to explain what it does.
3560
 
3561
In the past, we recommended not mentioning changes in non-software
3562
files (manuals, help files, etc.) in change logs.  However, we've been
3563
advised that it is a good idea to include them, for the sake of
3564
copyright records.
3565
 
3566
The easiest way to add an entry to @file{ChangeLog} is with the Emacs
3567
command @kbd{M-x add-change-log-entry}.  An entry should have an
3568
asterisk, the name of the changed file, and then in parentheses the name
3569
of the changed functions, variables or whatever, followed by a colon.
3570
Then describe the changes you made to that function or variable.
3571
 
3572
@node Style of Change Logs
3573
@subsection Style of Change Logs
3574
@cindex change logs, style
3575
 
3576
Here are some simple examples of change log entries, starting with the
3577
header line that says who made the change and when it was installed,
3578
followed by descriptions of specific changes.  (These examples are
3579
drawn from Emacs and GCC.)
3580
 
3581
@example
3582
1998-08-17  Richard Stallman  <rms@@gnu.org>
3583
 
3584
* register.el (insert-register): Return nil.
3585
(jump-to-register): Likewise.
3586
 
3587
* sort.el (sort-subr): Return nil.
3588
 
3589
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3590
Restart the tex shell if process is gone or stopped.
3591
(tex-shell-running): New function.
3592
 
3593
* expr.c (store_one_arg): Round size up for move_block_to_reg.
3594
(expand_call): Round up when emitting USE insns.
3595
* stmt.c (assign_parms): Round size up for move_block_from_reg.
3596
@end example
3597
 
3598
It's important to name the changed function or variable in full.  Don't
3599
abbreviate function or variable names, and don't combine them.
3600
Subsequent maintainers will often search for a function name to find all
3601
the change log entries that pertain to it; if you abbreviate the name,
3602
they won't find it when they search.
3603
 
3604
For example, some people are tempted to abbreviate groups of function
3605
names by writing @samp{* register.el (@{insert,jump-to@}-register)};
3606
this is not a good idea, since searching for @code{jump-to-register} or
3607
@code{insert-register} would not find that entry.
3608
 
3609
Separate unrelated change log entries with blank lines.  When two
3610
entries represent parts of the same change, so that they work together,
3611
then don't put blank lines between them.  Then you can omit the file
3612
name and the asterisk when successive entries are in the same file.
3613
 
3614
Break long lists of function names by closing continued lines with
3615
@samp{)}, rather than @samp{,}, and opening the continuation with
3616
@samp{(} as in this example:
3617
 
3618
@example
3619
* keyboard.c (menu_bar_items, tool_bar_items)
3620
(Fexecute_extended_command): Deal with `keymap' property.
3621
@end example
3622
 
3623
When you install someone else's changes, put the contributor's name in
3624
the change log entry rather than in the text of the entry.  In other
3625
words, write this:
3626
 
3627
@example
3628
2002-07-14  John Doe  <jdoe@@gnu.org>
3629
 
3630
        * sewing.c: Make it sew.
3631
@end example
3632
 
3633
@noindent
3634
rather than this:
3635
 
3636
@example
3637
2002-07-14  Usual Maintainer  <usual@@gnu.org>
3638
 
3639
        * sewing.c: Make it sew.  Patch by jdoe@@gnu.org.
3640
@end example
3641
 
3642
As for the date, that should be the date you applied the change.
3643
 
3644
@node Simple Changes
3645
@subsection Simple Changes
3646
 
3647
Certain simple kinds of changes don't need much detail in the change
3648
log.
3649
 
3650
When you change the calling sequence of a function in a simple fashion,
3651
and you change all the callers of the function to use the new calling
3652
sequence, there is no need to make individual entries for all the
3653
callers that you changed.  Just write in the entry for the function
3654
being called, ``All callers changed''---like this:
3655
 
3656
@example
3657
* keyboard.c (Fcommand_execute): New arg SPECIAL.
3658
All callers changed.
3659
@end example
3660
 
3661
When you change just comments or doc strings, it is enough to write an
3662
entry for the file, without mentioning the functions.  Just ``Doc
3663
fixes'' is enough for the change log.
3664
 
3665
There's no technical need to make change log entries for documentation
3666
files.  This is because documentation is not susceptible to bugs that
3667
are hard to fix.  Documentation does not consist of parts that must
3668
interact in a precisely engineered fashion.  To correct an error, you
3669
need not know the history of the erroneous passage; it is enough to
3670
compare what the documentation says with the way the program actually
3671
works.
3672
 
3673
However, you should keep change logs for documentation files when the
3674
project gets copyright assignments from its contributors, so as to
3675
make the records of authorship more accurate.
3676
 
3677
@node Conditional Changes
3678
@subsection Conditional Changes
3679
@cindex conditional changes, and change logs
3680
@cindex change logs, conditional changes
3681
 
3682
C programs often contain compile-time @code{#if} conditionals.  Many
3683
changes are conditional; sometimes you add a new definition which is
3684
entirely contained in a conditional.  It is very useful to indicate in
3685
the change log the conditions for which the change applies.
3686
 
3687
Our convention for indicating conditional changes is to use square
3688
brackets around the name of the condition.
3689
 
3690
Here is a simple example, describing a change which is conditional but
3691
does not have a function or entity name associated with it:
3692
 
3693
@example
3694
* xterm.c [SOLARIS2]: Include string.h.
3695
@end example
3696
 
3697
Here is an entry describing a new definition which is entirely
3698
conditional.  This new definition for the macro @code{FRAME_WINDOW_P} is
3699
used only when @code{HAVE_X_WINDOWS} is defined:
3700
 
3701
@example
3702
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3703
@end example
3704
 
3705
Here is an entry for a change within the function @code{init_display},
3706
whose definition as a whole is unconditional, but the changes themselves
3707
are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
3708
 
3709
@example
3710
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3711
@end example
3712
 
3713
Here is an entry for a change that takes affect only when
3714
a certain macro is @emph{not} defined:
3715
 
3716
@example
3717
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3718
@end example
3719
 
3720
@node Indicating the Part Changed
3721
@subsection Indicating the Part Changed
3722
 
3723
Indicate the part of a function which changed by using angle brackets
3724
enclosing an indication of what the changed part does.  Here is an entry
3725
for a change in the part of the function @code{sh-while-getopts} that
3726
deals with @code{sh} commands:
3727
 
3728
@example
3729
* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3730
user-specified option string is empty.
3731
@end example
3732
 
3733
 
3734
@node Man Pages
3735
@section Man Pages
3736
@cindex man pages
3737
 
3738
In the GNU project, man pages are secondary.  It is not necessary or
3739
expected for every GNU program to have a man page, but some of them do.
3740
It's your choice whether to include a man page in your program.
3741
 
3742
When you make this decision, consider that supporting a man page
3743
requires continual effort each time the program is changed.  The time
3744
you spend on the man page is time taken away from more useful work.
3745
 
3746
For a simple program which changes little, updating the man page may be
3747
a small job.  Then there is little reason not to include a man page, if
3748
you have one.
3749
 
3750
For a large program that changes a great deal, updating a man page may
3751
be a substantial burden.  If a user offers to donate a man page, you may
3752
find this gift costly to accept.  It may be better to refuse the man
3753
page unless the same person agrees to take full responsibility for
3754
maintaining it---so that you can wash your hands of it entirely.  If
3755
this volunteer later ceases to do the job, then don't feel obliged to
3756
pick it up yourself; it may be better to withdraw the man page from the
3757
distribution until someone else agrees to update it.
3758
 
3759
When a program changes only a little, you may feel that the
3760
discrepancies are small enough that the man page remains useful without
3761
updating.  If so, put a prominent note near the beginning of the man
3762
page explaining that you don't maintain it and that the Texinfo manual
3763
is more authoritative.  The note should say how to access the Texinfo
3764
documentation.
3765
 
3766
Be sure that man pages include a copyright statement and free license.
3767
The simple all-permissive license is appropriate for simple man pages
3768
(@pxref{License Notices for Other Files,,,maintain,Information for GNU
3769
Maintainers}).
3770
 
3771
For long man pages, with enough explanation and documentation that
3772
they can be considered true manuals, use the GFDL (@pxref{License for
3773
Manuals}).
3774
 
3775
Finally, the GNU help2man program
3776
(@uref{http://www.gnu.org/software/help2man/}) is one way to automate
3777
generation of a man page, in this case from @option{--help} output.
3778
This is sufficient in many cases.
3779
 
3780
@node Reading other Manuals
3781
@section Reading other Manuals
3782
 
3783
There may be non-free books or documentation files that describe the
3784
program you are documenting.
3785
 
3786
It is ok to use these documents for reference, just as the author of a
3787
new algebra textbook can read other books on algebra.  A large portion
3788
of any non-fiction book consists of facts, in this case facts about how
3789
a certain program works, and these facts are necessarily the same for
3790
everyone who writes about the subject.  But be careful not to copy your
3791
outline structure, wording, tables or examples from preexisting non-free
3792
documentation.  Copying from free documentation may be ok; please check
3793
with the FSF about the individual case.
3794
 
3795
@node Managing Releases
3796
@chapter The Release Process
3797
@cindex releasing
3798
 
3799
Making a release is more than just bundling up your source files in a
3800
tar file and putting it up for FTP.  You should set up your software so
3801
that it can be configured to run on a variety of systems.  Your Makefile
3802
should conform to the GNU standards described below, and your directory
3803
layout should also conform to the standards discussed below.  Doing so
3804
makes it easy to include your package into the larger framework of
3805
all GNU software.
3806
 
3807
@menu
3808
* Configuration::               How configuration of GNU packages should work.
3809
* Makefile Conventions::        Makefile conventions.
3810
* Releases::                    Making releases
3811
@end menu
3812
 
3813
@node Configuration
3814
@section How Configuration Should Work
3815
@cindex program configuration
3816
 
3817
@pindex configure
3818
Each GNU distribution should come with a shell script named
3819
@code{configure}.  This script is given arguments which describe the
3820
kind of machine and system you want to compile the program for.
3821
The @code{configure} script must record the configuration options so
3822
that they affect compilation.
3823
 
3824
The description here is the specification of the interface for the
3825
@code{configure} script in GNU packages.  Many packages implement it
3826
using GNU Autoconf (@pxref{Top,, Introduction, autoconf, Autoconf})
3827
and/or GNU Automake (@pxref{Top,, Introduction, automake, Automake}),
3828
but you do not have to use these tools.  You can implement it any way
3829
you like; for instance, by making @code{configure} be a wrapper around
3830
a completely different configuration system.
3831
 
3832
Another way for the @code{configure} script to operate is to make a
3833
link from a standard name such as @file{config.h} to the proper
3834
configuration file for the chosen system.  If you use this technique,
3835
the distribution should @emph{not} contain a file named
3836
@file{config.h}.  This is so that people won't be able to build the
3837
program without configuring it first.
3838
 
3839
Another thing that @code{configure} can do is to edit the Makefile.  If
3840
you do this, the distribution should @emph{not} contain a file named
3841
@file{Makefile}.  Instead, it should include a file @file{Makefile.in} which
3842
contains the input used for editing.  Once again, this is so that people
3843
won't be able to build the program without configuring it first.
3844
 
3845
If @code{configure} does write the @file{Makefile}, then @file{Makefile}
3846
should have a target named @file{Makefile} which causes @code{configure}
3847
to be rerun, setting up the same configuration that was set up last
3848
time.  The files that @code{configure} reads should be listed as
3849
dependencies of @file{Makefile}.
3850
 
3851
All the files which are output from the @code{configure} script should
3852
have comments at the beginning explaining that they were generated
3853
automatically using @code{configure}.  This is so that users won't think
3854
of trying to edit them by hand.
3855
 
3856
The @code{configure} script should write a file named @file{config.status}
3857
which describes which configuration options were specified when the
3858
program was last configured.  This file should be a shell script which,
3859
if run, will recreate the same configuration.
3860
 
3861
The @code{configure} script should accept an option of the form
3862
@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
3863
(if it is not the current directory).  This makes it possible to build
3864
the program in a separate directory, so that the actual source directory
3865
is not modified.
3866
 
3867
If the user does not specify @samp{--srcdir}, then @code{configure} should
3868
check both @file{.} and @file{..} to see if it can find the sources.  If
3869
it finds the sources in one of these places, it should use them from
3870
there.  Otherwise, it should report that it cannot find the sources, and
3871
should exit with nonzero status.
3872
 
3873
Usually the easy way to support @samp{--srcdir} is by editing a
3874
definition of @code{VPATH} into the Makefile.  Some rules may need to
3875
refer explicitly to the specified source directory.  To make this
3876
possible, @code{configure} can add to the Makefile a variable named
3877
@code{srcdir} whose value is precisely the specified directory.
3878
 
3879
In addition, the @samp{configure} script should take options
3880
corresponding to most of the standard directory variables
3881
(@pxref{Directory Variables}).  Here is the list:
3882
 
3883
@example
3884
--prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
3885
--sharedstatedir --localstatedir --libdir --includedir --oldincludedir
3886
--datarootdir --datadir --infodir --localedir --mandir --docdir
3887
--htmldir --dvidir --pdfdir --psdir
3888
@end example
3889
 
3890
The @code{configure} script should also take an argument which specifies the
3891
type of system to build the program for.  This argument should look like
3892
this:
3893
 
3894
@example
3895
@var{cpu}-@var{company}-@var{system}
3896
@end example
3897
 
3898
For example, an Athlon-based GNU/Linux system might be
3899
@samp{i686-pc-linux-gnu}.
3900
 
3901
The @code{configure} script needs to be able to decode all plausible
3902
alternatives for how to describe a machine.  Thus,
3903
@samp{athlon-pc-gnu/linux} would be a valid alias.  There is a shell
3904
script called
3905
@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD,
3906
@file{config.sub}} that you can use as a subroutine to validate system
3907
types and canonicalize aliases.
3908
 
3909
The @code{configure} script should also take the option
3910
@option{--build=@var{buildtype}}, which should be equivalent to a
3911
plain @var{buildtype} argument.  For example, @samp{configure
3912
--build=i686-pc-linux-gnu} is equivalent to @samp{configure
3913
i686-pc-linux-gnu}.  When the build type is not specified by an option
3914
or argument, the @code{configure} script should normally guess it using
3915
the shell script
3916
@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD,
3917
@file{config.guess}}.
3918
 
3919
@cindex optional features, configure-time
3920
Other options are permitted to specify in more detail the software
3921
or hardware present on the machine, to include or exclude optional parts
3922
of the package, or to adjust the name of some tools or arguments to them:
3923
 
3924
@table @samp
3925
@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
3926
Configure the package to build and install an optional user-level
3927
facility called @var{feature}.  This allows users to choose which
3928
optional features to include.  Giving an optional @var{parameter} of
3929
@samp{no} should omit @var{feature}, if it is built by default.
3930
 
3931
No @samp{--enable} option should @strong{ever} cause one feature to
3932
replace another.  No @samp{--enable} option should ever substitute one
3933
useful behavior for another useful behavior.  The only proper use for
3934
@samp{--enable} is for questions of whether to build part of the program
3935
or exclude it.
3936
 
3937
@item --with-@var{package}
3938
@c @r{[}=@var{parameter}@r{]}
3939
The package @var{package} will be installed, so configure this package
3940
to work with @var{package}.
3941
 
3942
@c  Giving an optional @var{parameter} of
3943
@c @samp{no} should omit @var{package}, if it is used by default.
3944
 
3945
Possible values of @var{package} include
3946
@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
3947
@samp{gdb},
3948
@samp{x},
3949
and
3950
@samp{x-toolkit}.
3951
 
3952
Do not use a @samp{--with} option to specify the file name to use to
3953
find certain files.  That is outside the scope of what @samp{--with}
3954
options are for.
3955
 
3956
@item @var{variable}=@var{value}
3957
Set the value of the variable @var{variable} to @var{value}.  This is
3958
used to override the default values of commands or arguments in the
3959
build process.  For example, the user could issue @samp{configure
3960
CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without
3961
the default optimization.
3962
 
3963
Specifying variables as arguments to @code{configure}, like this:
3964
@example
3965
./configure CC=gcc
3966
@end example
3967
is preferable to setting them in environment variables:
3968
@example
3969
CC=gcc ./configure
3970
@end example
3971
as it helps to recreate the same configuration later with
3972
@file{config.status}.  However, both methods should be supported.
3973
@end table
3974
 
3975
All @code{configure} scripts should accept all of the ``detail''
3976
options and the variable settings, whether or not they make any
3977
difference to the particular package at hand.  In particular, they
3978
should accept any option that starts with @samp{--with-} or
3979
@samp{--enable-}.  This is so users will be able to configure an
3980
entire GNU source tree at once with a single set of options.
3981
 
3982
You will note that the categories @samp{--with-} and @samp{--enable-}
3983
are narrow: they @strong{do not} provide a place for any sort of option
3984
you might think of.  That is deliberate.  We want to limit the possible
3985
configuration options in GNU software.  We do not want GNU programs to
3986
have idiosyncratic configuration options.
3987
 
3988
Packages that perform part of the compilation process may support
3989
cross-compilation.  In such a case, the host and target machines for the
3990
program may be different.
3991
 
3992
The @code{configure} script should normally treat the specified type of
3993
system as both the host and the target, thus producing a program which
3994
works for the same type of machine that it runs on.
3995
 
3996
To compile a program to run on a host type that differs from the build
3997
type, use the configure option @option{--host=@var{hosttype}}, where
3998
@var{hosttype} uses the same syntax as @var{buildtype}.  The host type
3999
normally defaults to the build type.
4000
 
4001
To configure a cross-compiler, cross-assembler, or what have you, you
4002
should specify a target different from the host, using the configure
4003
option @samp{--target=@var{targettype}}.  The syntax for
4004
@var{targettype} is the same as for the host type.  So the command would
4005
look like this:
4006
 
4007
@example
4008
./configure --host=@var{hosttype} --target=@var{targettype}
4009
@end example
4010
 
4011
The target type normally defaults to the host type.
4012
Programs for which cross-operation is not meaningful need not accept the
4013
@samp{--target} option, because configuring an entire operating system for
4014
cross-operation is not a meaningful operation.
4015
 
4016
Some programs have ways of configuring themselves automatically.  If
4017
your program is set up to do this, your @code{configure} script can simply
4018
ignore most of its arguments.
4019
 
4020
@comment The makefile standards are in a separate file that is also
4021
@comment included by make.texinfo.  Done by roland@gnu.ai.mit.edu on 1/6/93.
4022
@comment For this document, turn chapters into sections, etc.
4023
@lowersections
4024
@include make-stds.texi
4025
@raisesections
4026
 
4027
@node Releases
4028
@section Making Releases
4029
@cindex packaging
4030
 
4031
You should identify each release with a pair of version numbers, a
4032
major version and a minor.  We have no objection to using more than
4033
two numbers, but it is very unlikely that you really need them.
4034
 
4035
Package the distribution of @code{Foo version 69.96} up in a gzipped tar
4036
file with the name @file{foo-69.96.tar.gz}.  It should unpack into a
4037
subdirectory named @file{foo-69.96}.
4038
 
4039
Building and installing the program should never modify any of the files
4040
contained in the distribution.  This means that all the files that form
4041
part of the program in any way must be classified into @dfn{source
4042
files} and @dfn{non-source files}.  Source files are written by humans
4043
and never changed automatically; non-source files are produced from
4044
source files by programs under the control of the Makefile.
4045
 
4046
@cindex @file{README} file
4047
The distribution should contain a file named @file{README} which gives
4048
the name of the package, and a general description of what it does.  It
4049
is also good to explain the purpose of each of the first-level
4050
subdirectories in the package, if there are any.  The @file{README} file
4051
should either state the version number of the package, or refer to where
4052
in the package it can be found.
4053
 
4054
The @file{README} file should refer to the file @file{INSTALL}, which
4055
should contain an explanation of the installation procedure.
4056
 
4057
The @file{README} file should also refer to the file which contains the
4058
copying conditions.  The GNU GPL, if used, should be in a file called
4059
@file{COPYING}.  If the GNU LGPL is used, it should be in a file called
4060
@file{COPYING.LESSER}.
4061
 
4062
Naturally, all the source files must be in the distribution.  It is okay
4063
to include non-source files in the distribution, provided they are
4064
up-to-date and machine-independent, so that building the distribution
4065
normally will never modify them.  We commonly include non-source files
4066
produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
4067
unnecessary dependencies between our distributions, so that users can
4068
install whichever packages they want to install.
4069
 
4070
Non-source files that might actually be modified by building and
4071
installing the program should @strong{never} be included in the
4072
distribution.  So if you do distribute non-source files, always make
4073
sure they are up to date when you make a new distribution.
4074
 
4075
Make sure that all the files in the distribution are world-readable, and
4076
that directories are world-readable and world-searchable (octal mode 755).
4077
We used to recommend that all directories in the distribution also be
4078
world-writable (octal mode 777), because ancient versions of @code{tar}
4079
would otherwise not cope when extracting the archive as an unprivileged
4080
user.  That can easily lead to security issues when creating the archive,
4081
however, so now we recommend against that.
4082
 
4083
Don't include any symbolic links in the distribution itself.  If the tar
4084
file contains symbolic links, then people cannot even unpack it on
4085
systems that don't support symbolic links.  Also, don't use multiple
4086
names for one file in different directories, because certain file
4087
systems cannot handle this and that prevents unpacking the
4088
distribution.
4089
 
4090
Try to make sure that all the file names will be unique on MS-DOS.  A
4091
name on MS-DOS consists of up to 8 characters, optionally followed by a
4092
period and up to three characters.  MS-DOS will truncate extra
4093
characters both before and after the period.  Thus,
4094
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
4095
are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
4096
distinct.
4097
 
4098
@cindex @file{texinfo.tex}, in a distribution
4099
Include in your distribution a copy of the @file{texinfo.tex} you used
4100
to test print any @file{*.texinfo} or @file{*.texi} files.
4101
 
4102
Likewise, if your program uses small GNU software packages like regex,
4103
getopt, obstack, or termcap, include them in the distribution file.
4104
Leaving them out would make the distribution file a little smaller at
4105
the expense of possible inconvenience to a user who doesn't know what
4106
other files to get.
4107
 
4108
@node References
4109
@chapter References to Non-Free Software and Documentation
4110
@cindex references to non-free material
4111
 
4112
A GNU program should not recommend, promote, or grant legitimacy to
4113
the use of any non-free program.  Proprietary software is a social and
4114
ethical problem, and our aim is to put an end to that problem.  We
4115
can't stop some people from writing proprietary programs, or stop
4116
other people from using them, but we can and should refuse to
4117
advertise them to new potential customers, or to give the public the
4118
idea that their existence is ethical.
4119
 
4120
The GNU definition of free software is found on the GNU web site at
4121
@url{http://www.gnu.org/@/philosophy/@/free-sw.html}, and the definition
4122
of free documentation is found at
4123
@url{http://www.gnu.org/@/philosophy/@/free-doc.html}.  The terms ``free''
4124
and ``non-free'', used in this document, refer to those definitions.
4125
 
4126
A list of important licenses and whether they qualify as free is in
4127
@url{http://www.gnu.org/@/licenses/@/license-list.html}.  If it is not
4128
clear whether a license qualifies as free, please ask the GNU Project
4129
by writing to @email{licensing@@gnu.org}.  We will answer, and if the
4130
license is an important one, we will add it to the list.
4131
 
4132
When a non-free program or system is well known, you can mention it in
4133
passing---that is harmless, since users who might want to use it
4134
probably already know about it.  For instance, it is fine to explain
4135
how to build your package on top of some widely used non-free
4136
operating system, or how to use it together with some widely used
4137
non-free program.
4138
 
4139
However, you should give only the necessary information to help those
4140
who already use the non-free program to use your program with
4141
it---don't give, or refer to, any further information about the
4142
proprietary program, and don't imply that the proprietary program
4143
enhances your program, or that its existence is in any way a good
4144
thing.  The goal should be that people already using the proprietary
4145
program will get the advice they need about how to use your free
4146
program with it, while people who don't already use the proprietary
4147
program will not see anything likely to lead them to take an interest
4148
in it.
4149
 
4150
If a non-free program or system is obscure in your program's domain,
4151
your program should not mention or support it at all, since doing so
4152
would tend to popularize the non-free program more than it popularizes
4153
your program.  (You cannot hope to find many additional users for your
4154
program among the users of Foobar, if the existence of Foobar is not
4155
generally known among people who might want to use your program.)
4156
 
4157
Sometimes a program is free software in itself but depends on a
4158
non-free platform in order to run.  For instance, many Java programs
4159
depend on some non-free Java libraries.  To recommend or promote such
4160
a program is to promote the other programs it needs.  This is why we
4161
are careful about listing Java programs in the Free Software
4162
Directory: we don't want to promote the non-free Java libraries.
4163
 
4164
We hope this particular problem with Java will be gone by and by, as
4165
we replace the remaining non-free standard Java libraries with free
4166
software, but the general principle will remain the same: don't
4167
recommend, promote or legitimize programs that depend on non-free
4168
software to run.
4169
 
4170
Some free programs strongly encourage the use of non-free software.  A
4171
typical example is @command{mplayer}.  It is free software in itself,
4172
and the free code can handle some kinds of files.  However,
4173
@command{mplayer} recommends use of non-free codecs for other kinds of
4174
files, and users that install @command{mplayer} are very likely to
4175
install those codecs along with it.  To recommend @command{mplayer}
4176
is, in effect, to promote use of the non-free codecs.
4177
 
4178
Thus, you should not recommend programs that strongly encourage the
4179
use of non-free software.  This is why we do not list
4180
@command{mplayer} in the Free Software Directory.
4181
 
4182
A GNU package should not refer the user to any non-free documentation
4183
for free software.  Free documentation that can be included in free
4184
operating systems is essential for completing the GNU system, or any
4185
free operating system, so encouraging it is a priority; to recommend
4186
use of documentation that we are not allowed to include undermines the
4187
impetus for the community to produce documentation that we can
4188
include.  So GNU packages should never recommend non-free
4189
documentation.
4190
 
4191
By contrast, it is ok to refer to journal articles and textbooks in
4192
the comments of a program for explanation of how it functions, even
4193
though they are non-free.  This is because we don't include such
4194
things in the GNU system even they are free---they are outside the
4195
scope of what a software distribution needs to include.
4196
 
4197
Referring to a web site that describes or recommends a non-free
4198
program is promoting that program, so please do not make links (or
4199
mention by name) web sites that contain such material.  This policy is
4200
relevant particularly for the web pages for a GNU package.
4201
 
4202
Following links from nearly any web site can lead eventually to
4203
non-free software; this is inherent in the nature of the web.  So it
4204
makes no sense to criticize a site for having such links.  As long as
4205
the site does not itself recommend a non-free program, there is no
4206
need to consider the question of the sites that it links to for other
4207
reasons.
4208
 
4209
Thus, for example, you should not refer to AT&T's web site if that
4210
recommends AT&T's non-free software packages; you should not refer to
4211
a site that links to AT&T's site presenting it as a place to get some
4212
non-free program, because that link recommends and legitimizes the
4213
non-free program.  However, that a site contains a link to AT&T's web
4214
site for some other purpose (such as long-distance telephone service)
4215
is not an objection against it.
4216
 
4217
@node GNU Free Documentation License
4218
@appendix GNU Free Documentation License
4219
 
4220
@cindex FDL, GNU Free Documentation License
4221
@include fdl.texi
4222
 
4223
@node Index
4224
@unnumbered Index
4225
@printindex cp
4226
 
4227
@bye
4228
 
4229
Local variables:
4230
eval: (add-hook 'write-file-hooks 'time-stamp)
4231
time-stamp-start: "@set lastupdate "
4232
time-stamp-end: "$"
4233
time-stamp-format: "%:b %:d, %:y"
4234
compile-command: "cd work.s && make"
4235
End:

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.