|
2331
|
1 \input texinfo @c -*-texinfo-*- |
|
|
2 @c %**start of header |
|
|
3 @setfilename standards.info |
|
|
4 @settitle GNU Coding Standards |
|
|
5 @c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! |
|
|
6 @set lastupdate 17 November 1994 |
|
|
7 @c %**end of header |
|
|
8 |
|
|
9 @ifinfo |
|
|
10 @format |
|
|
11 START-INFO-DIR-ENTRY |
|
|
12 * Standards: (standards). GNU coding standards. |
|
|
13 END-INFO-DIR-ENTRY |
|
|
14 @end format |
|
|
15 @end ifinfo |
|
|
16 |
|
|
17 @setchapternewpage off |
|
|
18 |
|
|
19 @ifinfo |
|
|
20 GNU Coding Standards |
|
|
21 Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. |
|
|
22 |
|
|
23 Permission is granted to make and distribute verbatim copies of |
|
|
24 this manual provided the copyright notice and this permission notice |
|
|
25 are preserved on all copies. |
|
|
26 |
|
|
27 @ignore |
|
|
28 Permission is granted to process this file through TeX and print the |
|
|
29 results, provided the printed document carries copying permission |
|
|
30 notice identical to this one except for the removal of this paragraph |
|
|
31 (this paragraph not being relevant to the printed manual). |
|
|
32 @end ignore |
|
|
33 |
|
|
34 Permission is granted to copy and distribute modified versions of this |
|
|
35 manual under the conditions for verbatim copying, provided that the entire |
|
|
36 resulting derived work is distributed under the terms of a permission |
|
|
37 notice identical to this one. |
|
|
38 |
|
|
39 Permission is granted to copy and distribute translations of this manual |
|
|
40 into another language, under the above conditions for modified versions, |
|
|
41 except that this permission notice may be stated in a translation approved |
|
|
42 by the Free Software Foundation. |
|
|
43 @end ifinfo |
|
|
44 |
|
|
45 @titlepage |
|
|
46 @title GNU Coding Standards |
|
|
47 @author Richard Stallman |
|
|
48 @author last updated @value{lastupdate} |
|
|
49 @page |
|
|
50 |
|
|
51 @vskip 0pt plus 1filll |
|
|
52 Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc. |
|
|
53 |
|
|
54 Permission is granted to make and distribute verbatim copies of |
|
|
55 this manual provided the copyright notice and this permission notice |
|
|
56 are preserved on all copies. |
|
|
57 |
|
|
58 Permission is granted to copy and distribute modified versions of this |
|
|
59 manual under the conditions for verbatim copying, provided that the entire |
|
|
60 resulting derived work is distributed under the terms of a permission |
|
|
61 notice identical to this one. |
|
|
62 |
|
|
63 Permission is granted to copy and distribute translations of this manual |
|
|
64 into another language, under the above conditions for modified versions, |
|
|
65 except that this permission notice may be stated in a translation approved |
|
|
66 by the Free Software Foundation. |
|
|
67 @end titlepage |
|
|
68 |
|
|
69 @ifinfo |
|
|
70 @node Top, Preface, (dir), (dir) |
|
|
71 @top Version |
|
|
72 |
|
|
73 Last updated @value{lastupdate}. |
|
|
74 @end ifinfo |
|
|
75 |
|
|
76 @menu |
|
|
77 * Preface:: About the GNU Coding Standards |
|
|
78 * Reading Non-Free Code:: Referring to Proprietary Programs |
|
|
79 * Contributions:: Accepting Contributions |
|
|
80 * Change Logs:: Recording Changes |
|
|
81 * Compatibility:: Compatibility with Other Implementations |
|
|
82 * Makefile Conventions:: Makefile Conventions |
|
|
83 * Configuration:: How Configuration Should Work |
|
|
84 * Source Language:: Using Languages Other Than C |
|
|
85 * Formatting:: Formatting Your Source Code |
|
|
86 * Comments:: Commenting Your Work |
|
|
87 * Syntactic Conventions:: Clean Use of C Constructs |
|
|
88 * Names:: Naming Variables and Functions |
|
|
89 * Using Extensions:: Using Non-standard Features |
|
|
90 * System Functions:: Portability and ``standard'' library functions |
|
|
91 * Semantics:: Program Behavior for All Programs |
|
|
92 * Errors:: Formatting Error Messages |
|
|
93 * Libraries:: Library Behavior |
|
|
94 * Portability:: Portability As It Applies to GNU |
|
|
95 * User Interfaces:: Standards for Command Line Interfaces |
|
|
96 * Documentation:: Documenting Programs |
|
|
97 * Releases:: Making Releases |
|
|
98 @end menu |
|
|
99 |
|
|
100 @node Preface |
|
|
101 @chapter About the GNU Coding Standards |
|
|
102 |
|
|
103 The GNU Coding Standards were written by Richard Stallman and other GNU |
|
|
104 Project volunteers. Their purpose is to make the GNU system clean, |
|
|
105 consistent, and easy to install. This document can also be read as a |
|
|
106 guide to write portable, robust and reliable programs. It focuses on |
|
|
107 programs written in C, but many of the rules and principles are useful |
|
|
108 even if you write in another programming language. The rules often |
|
|
109 state reasons for writing in a certain way. |
|
|
110 |
|
|
111 Corrections or suggestions regarding this document should be sent to |
|
|
112 @code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a |
|
|
113 suggested new wording for it; our time is limited. We prefer a context |
|
|
114 diff to the @file{standards.texi} or @file{make-stds.texi} files, but if |
|
|
115 you don't have those files, please mail your suggestion anyway. |
|
|
116 |
|
|
117 This release of the GNU Coding Standards was last updated |
|
|
118 @value{lastupdate}. |
|
|
119 |
|
|
120 @node Reading Non-Free Code |
|
|
121 @chapter Referring to Proprietary Programs |
|
|
122 |
|
|
123 Don't in any circumstances refer to Unix source code for or during |
|
|
124 your work on GNU! (Or to any other proprietary programs.) |
|
|
125 |
|
|
126 If you have a vague recollection of the internals of a Unix program, |
|
|
127 this does not absolutely mean you can't write an imitation of it, but |
|
|
128 do try to organize the imitation internally along different lines, |
|
|
129 because this is likely to make the details of the Unix version |
|
|
130 irrelevant and dissimilar to your results. |
|
|
131 |
|
|
132 For example, Unix utilities were generally optimized to minimize |
|
|
133 memory use; if you go for speed instead, your program will be very |
|
|
134 different. You could keep the entire input file in core and scan it |
|
|
135 there instead of using stdio. Use a smarter algorithm discovered more |
|
|
136 recently than the Unix program. Eliminate use of temporary files. Do |
|
|
137 it in one pass instead of two (we did this in the assembler). |
|
|
138 |
|
|
139 Or, on the contrary, emphasize simplicity instead of speed. For some |
|
|
140 applications, the speed of today's computers makes simpler algorithms |
|
|
141 adequate. |
|
|
142 |
|
|
143 Or go for generality. For example, Unix programs often have static |
|
|
144 tables or fixed-size strings, which make for arbitrary limits; use |
|
|
145 dynamic allocation instead. Make sure your program handles NULs and |
|
|
146 other funny characters in the input files. Add a programming language |
|
|
147 for extensibility and write part of the program in that language. |
|
|
148 |
|
|
149 Or turn some parts of the program into independently usable libraries. |
|
|
150 Or use a simple garbage collector instead of tracking precisely when |
|
|
151 to free memory, or use a new GNU facility such as obstacks. |
|
|
152 |
|
|
153 |
|
|
154 @node Contributions |
|
|
155 @chapter Accepting Contributions |
|
|
156 |
|
|
157 If someone else sends you a piece of code to add to the program you are |
|
|
158 working on, we need legal papers to use it---the same sort of legal |
|
|
159 papers we will need to get from you. @emph{Each} significant |
|
|
160 contributor to a program must sign some sort of legal papers in order |
|
|
161 for us to have clear title to the program. The main author alone is not |
|
|
162 enough. |
|
|
163 |
|
|
164 So, before adding in any contributions from other people, tell us |
|
|
165 so we can arrange to get the papers. Then wait until we tell you |
|
|
166 that we have received the signed papers, before you actually use the |
|
|
167 contribution. |
|
|
168 |
|
|
169 This applies both before you release the program and afterward. If |
|
|
170 you receive diffs to fix a bug, and they make significant change, we |
|
|
171 need legal papers for it. |
|
|
172 |
|
|
173 You don't need papers for changes of a few lines here or there, since |
|
|
174 they are not significant for copyright purposes. Also, you don't need |
|
|
175 papers if all you get from the suggestion is some ideas, not actual code |
|
|
176 which you use. For example, if you write a different solution to the |
|
|
177 problem, you don't need to get papers. |
|
|
178 |
|
|
179 I know this is frustrating; it's frustrating for us as well. But if |
|
|
180 you don't wait, you are going out on a limb---for example, what if the |
|
|
181 contributor's employer won't sign a disclaimer? You might have to take |
|
|
182 that code out again! |
|
|
183 |
|
|
184 The very worst thing is if you forget to tell us about the other |
|
|
185 contributor. We could be very embarrassed in court some day as a |
|
|
186 result. |
|
|
187 |
|
|
188 @node Change Logs |
|
|
189 @chapter Change Logs |
|
|
190 |
|
|
191 Keep a change log for each directory, describing the changes made to |
|
|
192 source files in that directory. The purpose of this is so that people |
|
|
193 investigating bugs in the future will know about the changes that |
|
|
194 might have introduced the bug. Often a new bug can be found by |
|
|
195 looking at what was recently changed. More importantly, change logs |
|
|
196 can help eliminate conceptual inconsistencies between different parts |
|
|
197 of a program; they can give you a history of how the conflicting |
|
|
198 concepts arose. |
|
|
199 |
|
|
200 Use the Emacs command @kbd{M-x add-change-log-entry} to start a new |
|
|
201 entry in the |
|
|
202 change log. An entry should have an asterisk, the name of the changed |
|
|
203 file, and then in parentheses the name of the changed functions, |
|
|
204 variables or whatever, followed by a colon. Then describe the changes |
|
|
205 you made to that function or variable. |
|
|
206 |
|
|
207 Separate unrelated entries with blank lines. When two entries |
|
|
208 represent parts of the same change, so that they work together, then |
|
|
209 don't put blank lines between them. Then you can omit the file name |
|
|
210 and the asterisk when successive entries are in the same file. |
|
|
211 |
|
|
212 Here are some examples: |
|
|
213 |
|
|
214 @example |
|
|
215 * register.el (insert-register): Return nil. |
|
|
216 (jump-to-register): Likewise. |
|
|
217 |
|
|
218 * sort.el (sort-subr): Return nil. |
|
|
219 |
|
|
220 * tex-mode.el (tex-bibtex-file, tex-file, tex-region): |
|
|
221 Restart the tex shell if process is gone or stopped. |
|
|
222 (tex-shell-running): New function. |
|
|
223 |
|
|
224 * expr.c (store_one_arg): Round size up for move_block_to_reg. |
|
|
225 (expand_call): Round up when emitting USE insns. |
|
|
226 * stmt.c (assign_parms): Round size up for move_block_from_reg. |
|
|
227 @end example |
|
|
228 |
|
|
229 It's important to name the changed function or variable in full. Don't |
|
|
230 abbreviate them; don't combine them. Subsequent maintainers will often |
|
|
231 search for a function name to find all the change log entries that |
|
|
232 pertain to it; if you abbreviate the name, they won't find it when they |
|
|
233 search. For example, some people are tempted to abbreviate groups of |
|
|
234 function names by writing @samp{* register.el |
|
|
235 (@{insert,jump-to@}-register)}; this is not a good idea, since searching |
|
|
236 for @code{jump-to-register} or @code{insert-register} would not find the |
|
|
237 entry. |
|
|
238 |
|
|
239 There's no need to describe the full purpose of the changes or how they |
|
|
240 work together. It is better to put such explanations in comments in the |
|
|
241 code. That's why just ``New function'' is enough; there is a comment |
|
|
242 with the function in the source to explain what it does. |
|
|
243 |
|
|
244 However, sometimes it is useful to write one line to describe the |
|
|
245 overall purpose of a large batch of changes. |
|
|
246 |
|
|
247 You can think of the change log as a conceptual ``undo list'' which |
|
|
248 explains how earlier versions were different from the current version. |
|
|
249 People can see the current version; they don't need the change log |
|
|
250 to tell them what is in it. What they want from a change log is a |
|
|
251 clear explanation of how the earlier version differed. |
|
|
252 |
|
|
253 When you change the calling sequence of a function in a simple |
|
|
254 fashion, and you change all the callers of the function, there is no |
|
|
255 need to make individual entries for all the callers. Just write in |
|
|
256 the entry for the function being called, ``All callers changed.'' |
|
|
257 |
|
|
258 When you change just comments or doc strings, it is enough to write an |
|
|
259 entry for the file, without mentioning the functions. Write just, |
|
|
260 ``Doc fix.'' There's no need to keep a change log for documentation |
|
|
261 files. This is because documentation is not susceptible to bugs that |
|
|
262 are hard to fix. Documentation does not consist of parts that must |
|
|
263 interact in a precisely engineered fashion; to correct an error, you |
|
|
264 need not know the history of the erroneous passage. |
|
|
265 |
|
|
266 |
|
|
267 @node Compatibility |
|
|
268 @chapter Compatibility with Other Implementations |
|
|
269 |
|
|
270 With certain exceptions, utility programs and libraries for GNU should |
|
|
271 be upward compatible with those in Berkeley Unix, and upward compatible |
|
|
272 with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward |
|
|
273 compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. |
|
|
274 |
|
|
275 When these standards conflict, it is useful to offer compatibility |
|
|
276 modes for each of them. |
|
|
277 |
|
|
278 @sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel |
|
|
279 free to make the extensions anyway, and include a @samp{--ansi} or |
|
|
280 @samp{--compatible} option to turn them off. However, if the extension |
|
|
281 has a significant chance of breaking any real programs or scripts, |
|
|
282 then it is not really upward compatible. Try to redesign its |
|
|
283 interface. |
|
|
284 |
|
|
285 Many GNU programs suppress extensions that conflict with POSIX if the |
|
|
286 environment variable @code{POSIXLY_CORRECT} is defined (even if it is |
|
|
287 defined with a null value). Please make your program recognize this |
|
|
288 variable if appropriate. |
|
|
289 |
|
|
290 When a feature is used only by users (not by programs or command |
|
|
291 files), and it is done poorly in Unix, feel free to replace it |
|
|
292 completely with something totally different and better. (For example, |
|
|
293 vi is replaced with Emacs.) But it is nice to offer a compatible |
|
|
294 feature as well. (There is a free vi clone, so we offer it.) |
|
|
295 |
|
|
296 Additional useful features not in Berkeley Unix are welcome. |
|
|
297 Additional programs with no counterpart in Unix may be useful, |
|
|
298 but our first priority is usually to duplicate what Unix already |
|
|
299 has. |
|
|
300 |
|
|
301 @comment The makefile standards are in a separate file that is also |
|
|
302 @comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. |
|
|
303 @include make-stds.texi |
|
|
304 |
|
|
305 @node Configuration |
|
|
306 @chapter How Configuration Should Work |
|
|
307 |
|
|
308 Each GNU distribution should come with a shell script named |
|
|
309 @code{configure}. This script is given arguments which describe the |
|
|
310 kind of machine and system you want to compile the program for. |
|
|
311 |
|
|
312 The @code{configure} script must record the configuration options so |
|
|
313 that they affect compilation. |
|
|
314 |
|
|
315 One way to do this is to make a link from a standard name such as |
|
|
316 @file{config.h} to the proper configuration file for the chosen system. |
|
|
317 If you use this technique, the distribution should @emph{not} contain a |
|
|
318 file named @file{config.h}. This is so that people won't be able to |
|
|
319 build the program without configuring it first. |
|
|
320 |
|
|
321 Another thing that @code{configure} can do is to edit the Makefile. If |
|
|
322 you do this, the distribution should @emph{not} contain a file named |
|
|
323 @file{Makefile}. Instead, include a file @file{Makefile.in} which |
|
|
324 contains the input used for editing. Once again, this is so that people |
|
|
325 won't be able to build the program without configuring it first. |
|
|
326 |
|
|
327 If @code{configure} does write the @file{Makefile}, then @file{Makefile} |
|
|
328 should have a target named @file{Makefile} which causes @code{configure} |
|
|
329 to be rerun, setting up the same configuration that was set up last |
|
|
330 time. The files that @code{configure} reads should be listed as |
|
|
331 dependencies of @file{Makefile}. |
|
|
332 |
|
|
333 All the files which are output from the @code{configure} script should |
|
|
334 have comments at the beginning explaining that they were generated |
|
|
335 automatically using @code{configure}. This is so that users won't think |
|
|
336 of trying to edit them by hand. |
|
|
337 |
|
|
338 The @code{configure} script should write a file named @file{config.status} |
|
|
339 which describes which configuration options were specified when the |
|
|
340 program was last configured. This file should be a shell script which, |
|
|
341 if run, will recreate the same configuration. |
|
|
342 |
|
|
343 The @code{configure} script should accept an option of the form |
|
|
344 @samp{--srcdir=@var{dirname}} to specify the directory where sources are found |
|
|
345 (if it is not the current directory). This makes it possible to build |
|
|
346 the program in a separate directory, so that the actual source directory |
|
|
347 is not modified. |
|
|
348 |
|
|
349 If the user does not specify @samp{--srcdir}, then @code{configure} should |
|
|
350 check both @file{.} and @file{..} to see if it can find the sources. If |
|
|
351 it finds the sources in one of these places, it should use them from |
|
|
352 there. Otherwise, it should report that it cannot find the sources, and |
|
|
353 should exit with nonzero status. |
|
|
354 |
|
|
355 Usually the easy way to support @samp{--srcdir} is by editing a |
|
|
356 definition of @code{VPATH} into the Makefile. Some rules may need to |
|
|
357 refer explicitly to the specified source directory. To make this |
|
|
358 possible, @code{configure} can add to the Makefile a variable named |
|
|
359 @code{srcdir} whose value is precisely the specified directory. |
|
|
360 |
|
|
361 The @code{configure} script should also take an argument which specifies the |
|
|
362 type of system to build the program for. This argument should look like |
|
|
363 this: |
|
|
364 |
|
|
365 @example |
|
|
366 @var{cpu}-@var{company}-@var{system} |
|
|
367 @end example |
|
|
368 |
|
|
369 For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. |
|
|
370 |
|
|
371 The @code{configure} script needs to be able to decode all plausible |
|
|
372 alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} |
|
|
373 would be a valid alias. For many programs, @samp{vax-dec-ultrix} would |
|
|
374 be an alias for @samp{vax-dec-bsd}, simply because the differences |
|
|
375 between Ultrix and @sc{BSD} are rarely noticeable, but a few programs |
|
|
376 might need to distinguish them. |
|
|
377 @c Real 4.4BSD now runs on some Suns. |
|
|
378 |
|
|
379 There is a shell script called @file{config.sub} that you can use |
|
|
380 as a subroutine to validate system types and canonicalize aliases. |
|
|
381 |
|
|
382 Other options are permitted to specify in more detail the software |
|
|
383 or hardware present on the machine, and include or exclude optional |
|
|
384 parts of the package: |
|
|
385 |
|
|
386 @table @samp |
|
|
387 @item --enable-@var{feature}@r{[}=@var{parameter}@r{]} |
|
|
388 Configure the package to build and install an optional user-level |
|
|
389 facility called @var{feature}. This allows users to choose which |
|
|
390 optional features to include. Giving an optional @var{parameter} of |
|
|
391 @samp{no} should omit @var{feature}, if it is built by default. |
|
|
392 |
|
|
393 No @samp{--enable} option should @strong{ever} cause one feature to |
|
|
394 replace another. No @samp{--enable} option should ever substitute one |
|
|
395 useful behavior for another useful behavior. The only proper use for |
|
|
396 @samp{--enable} is for questions of whether to build part of the program |
|
|
397 or exclude it. |
|
|
398 |
|
|
399 @item --with-@var{package} |
|
|
400 @c @r{[}=@var{parameter}@r{]} |
|
|
401 The package @var{package} will be installed, so configure this package |
|
|
402 to work with @var{package}. |
|
|
403 |
|
|
404 @c Giving an optional @var{parameter} of |
|
|
405 @c @samp{no} should omit @var{package}, if it is used by default. |
|
|
406 |
|
|
407 Possible values of @var{package} include @samp{x}, @samp{x-toolkit}, |
|
|
408 @samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and |
|
|
409 @samp{gdb}. |
|
|
410 |
|
|
411 Do not use a @samp{--with} option to specify the file name to use to |
|
|
412 find certain files. That is outside the scope of what @samp{--with} |
|
|
413 options are for. |
|
|
414 |
|
|
415 @item --nfp |
|
|
416 The target machine has no floating point processor. |
|
|
417 |
|
|
418 @item --gas |
|
|
419 The target machine assembler is GAS, the GNU assembler. |
|
|
420 This is obsolete; users should use @samp{--with-gnu-as} instead. |
|
|
421 |
|
|
422 @item --x |
|
|
423 The target machine has the X Window System installed. |
|
|
424 This is obsolete; users should use @samp{--with-x} instead. |
|
|
425 @end table |
|
|
426 |
|
|
427 All @code{configure} scripts should accept all of these ``detail'' |
|
|
428 options, whether or not they make any difference to the particular |
|
|
429 package at hand. In particular, they should accept any option that |
|
|
430 starts with @samp{--with-} or @samp{--enable-}. This is so users will |
|
|
431 be able to configure an entire GNU source tree at once with a single set |
|
|
432 of options. |
|
|
433 |
|
|
434 You will note that the categories @samp{--with-} and @samp{--enable-} |
|
|
435 are narrow: they @strong{do not} provide a place for any sort of option |
|
|
436 you might think of. That is deliberate. We want to limit the possible |
|
|
437 configuration options in GNU software. We do not want GNU programs to |
|
|
438 have idiosyncratic configuration options. |
|
|
439 |
|
|
440 Packages that perform part of compilation may support cross-compilation. |
|
|
441 In such a case, the host and target machines for the program may be |
|
|
442 different. The @code{configure} script should normally treat the |
|
|
443 specified type of system as both the host and the target, thus producing |
|
|
444 a program which works for the same type of machine that it runs on. |
|
|
445 |
|
|
446 The way to build a cross-compiler, cross-assembler, or what have you, is |
|
|
447 to specify the option @samp{--host=@var{hosttype}} when running |
|
|
448 @code{configure}. This specifies the host system without changing the |
|
|
449 type of target system. The syntax for @var{hosttype} is the same as |
|
|
450 described above. |
|
|
451 |
|
|
452 Bootstrapping a cross-compiler requires compiling it on a machine other |
|
|
453 than the host it will run on. Compilation packages accept a |
|
|
454 configuration option @samp{--build=@var{hosttype}} for specifying the |
|
|
455 configuration on which you will compile them, in case that is different |
|
|
456 from the host. |
|
|
457 |
|
|
458 Programs for which cross-operation is not meaningful need not accept the |
|
|
459 @samp{--host} option, because configuring an entire operating system for |
|
|
460 cross-operation is not a meaningful thing. |
|
|
461 |
|
|
462 Some programs have ways of configuring themselves automatically. If |
|
|
463 your program is set up to do this, your @code{configure} script can simply |
|
|
464 ignore most of its arguments. |
|
|
465 |
|
|
466 @node Source Language |
|
|
467 @chapter Using Languages Other Than C |
|
|
468 |
|
|
469 Using a language other than C is like using a non-standard feature: it |
|
|
470 will cause trouble for users. Even if GCC supports the other language, |
|
|
471 users may find it inconvenient to have to install the compiler for that |
|
|
472 other language in order to build your program. So please write in C. |
|
|
473 |
|
|
474 There are three exceptions for this rule: |
|
|
475 |
|
|
476 @itemize @bullet |
|
|
477 @item |
|
|
478 It is okay to use a special language if the same program contains an |
|
|
479 interpreter for that language. |
|
|
480 |
|
|
481 Thus, it is not a problem that GNU Emacs contains code written in Emacs |
|
|
482 Lisp, because it comes with a Lisp interpreter. |
|
|
483 |
|
|
484 @item |
|
|
485 It is okay to use another language in a tool specifically intended for |
|
|
486 use with that language. |
|
|
487 |
|
|
488 This is okay because the only people who want to build the tool will be |
|
|
489 those who have installed the other language anyway. |
|
|
490 |
|
|
491 @item |
|
|
492 If an application is not of extremely widespread interest, then perhaps |
|
|
493 it's not important if the application is inconvenient to install. |
|
|
494 @end itemize |
|
|
495 |
|
|
496 @node Formatting |
|
|
497 @chapter Formatting Your Source Code |
|
|
498 |
|
|
499 It is important to put the open-brace that starts the body of a C |
|
|
500 function in column zero, and avoid putting any other open-brace or |
|
|
501 open-parenthesis or open-bracket in column zero. Several tools look |
|
|
502 for open-braces in column zero to find the beginnings of C functions. |
|
|
503 These tools will not work on code not formatted that way. |
|
|
504 |
|
|
505 It is also important for function definitions to start the name of the |
|
|
506 function in column zero. This helps people to search for function |
|
|
507 definitions, and may also help certain tools recognize them. Thus, |
|
|
508 the proper format is this: |
|
|
509 |
|
|
510 @example |
|
|
511 static char * |
|
|
512 concat (s1, s2) /* Name starts in column zero here */ |
|
|
513 char *s1, *s2; |
|
|
514 @{ /* Open brace in column zero here */ |
|
|
515 @dots{} |
|
|
516 @} |
|
|
517 @end example |
|
|
518 |
|
|
519 @noindent |
|
|
520 or, if you want to use @sc{ANSI} C, format the definition like this: |
|
|
521 |
|
|
522 @example |
|
|
523 static char * |
|
|
524 concat (char *s1, char *s2) |
|
|
525 @{ |
|
|
526 @dots{} |
|
|
527 @} |
|
|
528 @end example |
|
|
529 |
|
|
530 In @sc{ANSI} C, if the arguments don't fit nicely on one line, |
|
|
531 split it like this: |
|
|
532 |
|
|
533 @example |
|
|
534 int |
|
|
535 lots_of_args (int an_integer, long a_long, short a_short, |
|
|
536 double a_double, float a_float) |
|
|
537 @dots{} |
|
|
538 @end example |
|
|
539 |
|
|
540 For the body of the function, we prefer code formatted like this: |
|
|
541 |
|
|
542 @example |
|
|
543 if (x < foo (y, z)) |
|
|
544 haha = bar[4] + 5; |
|
|
545 else |
|
|
546 @{ |
|
|
547 while (z) |
|
|
548 @{ |
|
|
549 haha += foo (z, z); |
|
|
550 z--; |
|
|
551 @} |
|
|
552 return ++x + bar (); |
|
|
553 @} |
|
|
554 @end example |
|
|
555 |
|
|
556 We find it easier to read a program when it has spaces before the |
|
|
557 open-parentheses and after the commas. Especially after the commas. |
|
|
558 |
|
|
559 When you split an expression into multiple lines, split it |
|
|
560 before an operator, not after one. Here is the right way: |
|
|
561 |
|
|
562 @example |
|
|
563 if (foo_this_is_long && bar > win (x, y, z) |
|
|
564 && remaining_condition) |
|
|
565 @end example |
|
|
566 |
|
|
567 Try to avoid having two operators of different precedence at the same |
|
|
568 level of indentation. For example, don't write this: |
|
|
569 |
|
|
570 @example |
|
|
571 mode = (inmode[j] == VOIDmode |
|
|
572 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) |
|
|
573 ? outmode[j] : inmode[j]); |
|
|
574 @end example |
|
|
575 |
|
|
576 Instead, use extra parentheses so that the indentation shows the nesting: |
|
|
577 |
|
|
578 @example |
|
|
579 mode = ((inmode[j] == VOIDmode |
|
|
580 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) |
|
|
581 ? outmode[j] : inmode[j]); |
|
|
582 @end example |
|
|
583 |
|
|
584 Insert extra parentheses so that Emacs will indent the code properly. |
|
|
585 For example, the following indentation looks nice if you do it by hand, |
|
|
586 but Emacs would mess it up: |
|
|
587 |
|
|
588 @example |
|
|
589 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 |
|
|
590 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; |
|
|
591 @end example |
|
|
592 |
|
|
593 But adding a set of parentheses solves the problem: |
|
|
594 |
|
|
595 @example |
|
|
596 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 |
|
|
597 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); |
|
|
598 @end example |
|
|
599 |
|
|
600 Format do-while statements like this: |
|
|
601 |
|
|
602 @example |
|
|
603 do |
|
|
604 @{ |
|
|
605 a = foo (a); |
|
|
606 @} |
|
|
607 while (a > 0); |
|
|
608 @end example |
|
|
609 |
|
|
610 Please use formfeed characters (control-L) to divide the program into |
|
|
611 pages at logical places (but not within a function). It does not matter |
|
|
612 just how long the pages are, since they do not have to fit on a printed |
|
|
613 page. The formfeeds should appear alone on lines by themselves. |
|
|
614 |
|
|
615 |
|
|
616 @node Comments |
|
|
617 @chapter Commenting Your Work |
|
|
618 |
|
|
619 Every program should start with a comment saying briefly what it is for. |
|
|
620 Example: @samp{fmt - filter for simple filling of text}. |
|
|
621 |
|
|
622 Please put a comment on each function saying what the function does, |
|
|
623 what sorts of arguments it gets, and what the possible values of |
|
|
624 arguments mean and are used for. It is not necessary to duplicate in |
|
|
625 words the meaning of the C argument declarations, if a C type is being |
|
|
626 used in its customary fashion. If there is anything nonstandard about |
|
|
627 its use (such as an argument of type @code{char *} which is really the |
|
|
628 address of the second character of a string, not the first), or any |
|
|
629 possible values that would not work the way one would expect (such as, |
|
|
630 that strings containing newlines are not guaranteed to work), be sure |
|
|
631 to say so. |
|
|
632 |
|
|
633 Also explain the significance of the return value, if there is one. |
|
|
634 |
|
|
635 Please put two spaces after the end of a sentence in your comments, so |
|
|
636 that the Emacs sentence commands will work. Also, please write |
|
|
637 complete sentences and capitalize the first word. If a lower-case |
|
|
638 identifer comes at the beginning of a sentence, don't capitalize it! |
|
|
639 Changing the spelling makes it a different identifier. If you don't |
|
|
640 like starting a sentence with a lower case letter, write the sentence |
|
|
641 differently (e.g., ``The identifier lower-case is @dots{}''). |
|
|
642 |
|
|
643 The comment on a function is much clearer if you use the argument |
|
|
644 names to speak about the argument values. The variable name itself |
|
|
645 should be lower case, but write it in upper case when you are speaking |
|
|
646 about the value rather than the variable itself. Thus, ``the inode |
|
|
647 number NODE_NUM'' rather than ``an inode''. |
|
|
648 |
|
|
649 There is usually no purpose in restating the name of the function in |
|
|
650 the comment before it, because the reader can see that for himself. |
|
|
651 There might be an exception when the comment is so long that the function |
|
|
652 itself would be off the bottom of the screen. |
|
|
653 |
|
|
654 There should be a comment on each static variable as well, like this: |
|
|
655 |
|
|
656 @example |
|
|
657 /* Nonzero means truncate lines in the display; |
|
|
658 zero means continue them. */ |
|
|
659 int truncate_lines; |
|
|
660 @end example |
|
|
661 |
|
|
662 Every @samp{#endif} should have a comment, except in the case of short |
|
|
663 conditionals (just a few lines) that are not nested. The comment should |
|
|
664 state the condition of the conditional that is ending, @emph{including |
|
|
665 its sense}. @samp{#else} should have a comment describing the condition |
|
|
666 @emph{and sense} of the code that follows. For example: |
|
|
667 |
|
|
668 @example |
|
|
669 #ifdef foo |
|
|
670 @dots{} |
|
|
671 #else /* not foo */ |
|
|
672 @dots{} |
|
|
673 #endif /* not foo */ |
|
|
674 @end example |
|
|
675 |
|
|
676 @noindent |
|
|
677 but, by contrast, write the comments this way for a @samp{#ifndef}: |
|
|
678 |
|
|
679 @example |
|
|
680 #ifndef foo |
|
|
681 @dots{} |
|
|
682 #else /* foo */ |
|
|
683 @dots{} |
|
|
684 #endif /* foo */ |
|
|
685 @end example |
|
|
686 |
|
|
687 |
|
|
688 @node Syntactic Conventions |
|
|
689 @chapter Clean Use of C Constructs |
|
|
690 |
|
|
691 Please explicitly declare all arguments to functions. |
|
|
692 Don't omit them just because they are @code{int}s. |
|
|
693 |
|
|
694 Declarations of external functions and functions to appear later in the |
|
|
695 source file should all go in one place near the beginning of the file |
|
|
696 (somewhere before the first function definition in the file), or else |
|
|
697 should go in a header file. Don't put @code{extern} declarations inside |
|
|
698 functions. |
|
|
699 |
|
|
700 It used to be common practice to use the same local variables (with |
|
|
701 names like @code{tem}) over and over for different values within one |
|
|
702 function. Instead of doing this, it is better declare a separate local |
|
|
703 variable for each distinct purpose, and give it a name which is |
|
|
704 meaningful. This not only makes programs easier to understand, it also |
|
|
705 facilitates optimization by good compilers. You can also move the |
|
|
706 declaration of each local variable into the smallest scope that includes |
|
|
707 all its uses. This makes the program even cleaner. |
|
|
708 |
|
|
709 Don't use local variables or parameters that shadow global identifiers. |
|
|
710 |
|
|
711 Don't declare multiple variables in one declaration that spans lines. |
|
|
712 Start a new declaration on each line, instead. For example, instead |
|
|
713 of this: |
|
|
714 |
|
|
715 @example |
|
|
716 int foo, |
|
|
717 bar; |
|
|
718 @end example |
|
|
719 |
|
|
720 @noindent |
|
|
721 write either this: |
|
|
722 |
|
|
723 @example |
|
|
724 int foo, bar; |
|
|
725 @end example |
|
|
726 |
|
|
727 @noindent |
|
|
728 or this: |
|
|
729 |
|
|
730 @example |
|
|
731 int foo; |
|
|
732 int bar; |
|
|
733 @end example |
|
|
734 |
|
|
735 @noindent |
|
|
736 (If they are global variables, each should have a comment preceding it |
|
|
737 anyway.) |
|
|
738 |
|
|
739 When you have an @code{if}-@code{else} statement nested in another |
|
|
740 @code{if} statement, always put braces around the @code{if}-@code{else}. |
|
|
741 Thus, never write like this: |
|
|
742 |
|
|
743 @example |
|
|
744 if (foo) |
|
|
745 if (bar) |
|
|
746 win (); |
|
|
747 else |
|
|
748 lose (); |
|
|
749 @end example |
|
|
750 |
|
|
751 @noindent |
|
|
752 always like this: |
|
|
753 |
|
|
754 @example |
|
|
755 if (foo) |
|
|
756 @{ |
|
|
757 if (bar) |
|
|
758 win (); |
|
|
759 else |
|
|
760 lose (); |
|
|
761 @} |
|
|
762 @end example |
|
|
763 |
|
|
764 If you have an @code{if} statement nested inside of an @code{else} |
|
|
765 statement, either write @code{else if} on one line, like this, |
|
|
766 |
|
|
767 @example |
|
|
768 if (foo) |
|
|
769 @dots{} |
|
|
770 else if (bar) |
|
|
771 @dots{} |
|
|
772 @end example |
|
|
773 |
|
|
774 @noindent |
|
|
775 with its @code{then}-part indented like the preceding @code{then}-part, |
|
|
776 or write the nested @code{if} within braces like this: |
|
|
777 |
|
|
778 @example |
|
|
779 if (foo) |
|
|
780 @dots{} |
|
|
781 else |
|
|
782 @{ |
|
|
783 if (bar) |
|
|
784 @dots{} |
|
|
785 @} |
|
|
786 @end example |
|
|
787 |
|
|
788 Don't declare both a structure tag and variables or typedefs in the |
|
|
789 same declaration. Instead, declare the structure tag separately |
|
|
790 and then use it to declare the variables or typedefs. |
|
|
791 |
|
|
792 Try to avoid assignments inside @code{if}-conditions. For example, |
|
|
793 don't write this: |
|
|
794 |
|
|
795 @example |
|
|
796 if ((foo = (char *) malloc (sizeof *foo)) == 0) |
|
|
797 fatal ("virtual memory exhausted"); |
|
|
798 @end example |
|
|
799 |
|
|
800 @noindent |
|
|
801 instead, write this: |
|
|
802 |
|
|
803 @example |
|
|
804 foo = (char *) malloc (sizeof *foo); |
|
|
805 if (foo == 0) |
|
|
806 fatal ("virtual memory exhausted"); |
|
|
807 @end example |
|
|
808 |
|
|
809 Don't make the program ugly to placate @code{lint}. Please don't insert any |
|
|
810 casts to @code{void}. Zero without a cast is perfectly fine as a null |
|
|
811 pointer constant. |
|
|
812 |
|
|
813 @node Names |
|
|
814 @chapter Naming Variables and Functions |
|
|
815 |
|
|
816 Please use underscores to separate words in a name, so that the Emacs |
|
|
817 word commands can be useful within them. Stick to lower case; reserve |
|
|
818 upper case for macros and @code{enum} constants, and for name-prefixes |
|
|
819 that follow a uniform convention. |
|
|
820 |
|
|
821 For example, you should use names like @code{ignore_space_change_flag}; |
|
|
822 don't use names like @code{iCantReadThis}. |
|
|
823 |
|
|
824 Variables that indicate whether command-line options have been |
|
|
825 specified should be named after the meaning of the option, not after |
|
|
826 the option-letter. A comment should state both the exact meaning of |
|
|
827 the option and its letter. For example, |
|
|
828 |
|
|
829 @example |
|
|
830 /* Ignore changes in horizontal whitespace (-b). */ |
|
|
831 int ignore_space_change_flag; |
|
|
832 @end example |
|
|
833 |
|
|
834 When you want to define names with constant integer values, use |
|
|
835 @code{enum} rather than @samp{#define}. GDB knows about enumeration |
|
|
836 constants. |
|
|
837 |
|
|
838 Use file names of 14 characters or less, to avoid creating gratuitous |
|
|
839 problems on System V. You can use the program @code{doschk} to test for |
|
|
840 this. @code{doschk} also tests for potential name conflicts if the |
|
|
841 files were loaded onto an MS-DOS file system---something you may or may |
|
|
842 not care about. |
|
|
843 |
|
|
844 |
|
|
845 @node Using Extensions |
|
|
846 @chapter Using Non-standard Features |
|
|
847 |
|
|
848 Many GNU facilities that already exist support a number of convenient |
|
|
849 extensions over the comparable Unix facilities. Whether to use these |
|
|
850 extensions in implementing your program is a difficult question. |
|
|
851 |
|
|
852 On the one hand, using the extensions can make a cleaner program. |
|
|
853 On the other hand, people will not be able to build the program |
|
|
854 unless the other GNU tools are available. This might cause the |
|
|
855 program to work on fewer kinds of machines. |
|
|
856 |
|
|
857 With some extensions, it might be easy to provide both alternatives. |
|
|
858 For example, you can define functions with a ``keyword'' @code{INLINE} |
|
|
859 and define that as a macro to expand into either @code{inline} or |
|
|
860 nothing, depending on the compiler. |
|
|
861 |
|
|
862 In general, perhaps it is best not to use the extensions if you can |
|
|
863 straightforwardly do without them, but to use the extensions if they |
|
|
864 are a big improvement. |
|
|
865 |
|
|
866 An exception to this rule are the large, established programs (such as |
|
|
867 Emacs) which run on a great variety of systems. Such programs would |
|
|
868 be broken by use of GNU extensions. |
|
|
869 |
|
|
870 Another exception is for programs that are used as part of |
|
|
871 compilation: anything that must be compiled with other compilers in |
|
|
872 order to bootstrap the GNU compilation facilities. If these require |
|
|
873 the GNU compiler, then no one can compile them without having them |
|
|
874 installed already. That would be no good. |
|
|
875 |
|
|
876 Since most computer systems do not yet implement @sc{ANSI} C, using the |
|
|
877 @sc{ANSI} C features is effectively using a GNU extension, so the |
|
|
878 same considerations apply. (Except for @sc{ANSI} features that we |
|
|
879 discourage, such as trigraphs---don't ever use them.) |
|
|
880 |
|
|
881 |
|
|
882 @node System Functions |
|
|
883 @chapter Calling System Functions |
|
|
884 |
|
|
885 C implementations differ substantially. ANSI C reduces but does not |
|
|
886 eliminate the incompatibilities; meanwhile, many users wish to compile |
|
|
887 GNU software with pre-ANSI compilers. This chapter gives |
|
|
888 recommendations for how to use the more or less standard C library |
|
|
889 functions to avoid unnecessary loss of portability. |
|
|
890 |
|
|
891 @itemize @bullet |
|
|
892 @item |
|
|
893 Don't use the value of @code{sprintf}. It returns the number of |
|
|
894 characters written on some systems, but not on all systems. |
|
|
895 |
|
|
896 @item |
|
|
897 Don't declare system functions explicitly. |
|
|
898 |
|
|
899 Almost any declaration for a system function is wrong on some system. |
|
|
900 To minimize conflicts, leave it to the system header files to declare |
|
|
901 system functions. If the headers don't declare a function, let it |
|
|
902 remain undeclared. |
|
|
903 |
|
|
904 While it may seem unclean to use a function without declaring it, in |
|
|
905 practice this works fine for most system library functions on the |
|
|
906 systems where this really happens. The problem is only theoretical. By |
|
|
907 contrast, actual declarations have frequently caused actual conflicts. |
|
|
908 |
|
|
909 @item |
|
|
910 If you must declare a system function, don't specify the argument types. |
|
|
911 Use an old-style declaration, not an ANSI prototype. The more you |
|
|
912 specify about the function, the more likely a conflict. |
|
|
913 |
|
|
914 @item |
|
|
915 In particular, don't unconditionally declare @code{malloc} or |
|
|
916 @code{realloc}. |
|
|
917 |
|
|
918 Most GNU programs use those functions just once, in functions |
|
|
919 conventionally named @code{xmalloc} and @code{xrealloc}. These |
|
|
920 functions call @code{malloc} and @code{realloc}, respectively, and |
|
|
921 check the results. |
|
|
922 |
|
|
923 Because @code{xmalloc} and @code{xrealloc} are defined in your program, |
|
|
924 you can declare them in other files without any risk of type conflict. |
|
|
925 |
|
|
926 On most systems, @code{int} is the same length as a pointer; thus, the |
|
|
927 calls to @code{malloc} and @code{realloc} work fine. For the few |
|
|
928 exceptional systems (mostly 64-bit machines), you can use |
|
|
929 @strong{conditionalized} declarations of @code{malloc} and |
|
|
930 @code{realloc}---or put these declarations in configuration files |
|
|
931 specific to those systems. |
|
|
932 |
|
|
933 @item |
|
|
934 The string functions require special treatment. Some Unix systems have |
|
|
935 a header file @file{string.h}; other have @file{strings.h}. Neither |
|
|
936 file name is portable. There are two things you can do: use Autoconf to |
|
|
937 figure out which file to include, or don't include either file. |
|
|
938 |
|
|
939 @item |
|
|
940 If you don't include either strings file, you can't get declarations for |
|
|
941 the string functions from the header file in the usual way. |
|
|
942 |
|
|
943 That causes less of a problem than you might think. The newer ANSI |
|
|
944 string functions are off-limits anyway because many systems still don't |
|
|
945 support them. The string functions you can use are these: |
|
|
946 |
|
|
947 @example |
|
|
948 strcpy strncpy strcat strncat |
|
|
949 strlen strcmp strncmp |
|
|
950 strchr strrchr |
|
|
951 @end example |
|
|
952 |
|
|
953 The copy and concatenate functions work fine without a declaration as |
|
|
954 long as you don't use their values. Using their values without a |
|
|
955 declaration fails on systems where the width of a pointer differs from |
|
|
956 the width of @code{int}, and perhaps in other cases. It is trivial to |
|
|
957 avoid using their values, so do that. |
|
|
958 |
|
|
959 The compare functions and @code{strlen} work fine without a declaration |
|
|
960 on most systems, possibly all the ones that GNU software runs on. |
|
|
961 You may find it necessary to declare them @strong{conditionally} on a |
|
|
962 few systems. |
|
|
963 |
|
|
964 The search functions must be declared to return @code{char *}. Luckily, |
|
|
965 there is no variation in the data type they return. But there is |
|
|
966 variation in their names. Some systems give these functions the names |
|
|
967 @code{index} and @code{rindex}; other systems use the names |
|
|
968 @code{strchr} and @code{strrchr}. Some systems support both pairs of |
|
|
969 names, but neither pair works on all systems. |
|
|
970 |
|
|
971 You should pick a single pair of names and use it throughout your |
|
|
972 program. (Nowadays, it is better to choose @code{strchr} and |
|
|
973 @code{strrchr}.) Declare both of those names as functions returning |
|
|
974 @code{char *}. On systems which don't support those names, define them |
|
|
975 as macros in terms of the other pair. For example, here is what to put |
|
|
976 at the beginning of your file (or in a header) if you want to use the |
|
|
977 names @code{strchr} and @code{strrchr} throughout: |
|
|
978 |
|
|
979 @example |
|
|
980 #ifndef HAVE_STRCHR |
|
|
981 #define strchr index |
|
|
982 #endif |
|
|
983 #ifndef HAVE_STRRCHR |
|
|
984 #define strrchr rindex |
|
|
985 #endif |
|
|
986 |
|
|
987 char *strchr (); |
|
|
988 char *strrchr (); |
|
|
989 @end example |
|
|
990 @end itemize |
|
|
991 |
|
|
992 Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are |
|
|
993 macros defined in systems where the corresponding functions exist. |
|
|
994 One way to get them properly defined is to use Autoconf. |
|
|
995 |
|
|
996 @node Semantics |
|
|
997 @chapter Program Behavior for All Programs |
|
|
998 |
|
|
999 Avoid arbitrary limits on the length or number of @emph{any} data |
|
|
1000 structure, including filenames, lines, files, and symbols, by allocating |
|
|
1001 all data structures dynamically. In most Unix utilities, ``long lines |
|
|
1002 are silently truncated''. This is not acceptable in a GNU utility. |
|
|
1003 |
|
|
1004 Utilities reading files should not drop NUL characters, or any other |
|
|
1005 nonprinting characters @emph{including those with codes above 0177}. The |
|
|
1006 only sensible exceptions would be utilities specifically intended for |
|
|
1007 interface to certain types of printers that can't handle those characters. |
|
|
1008 |
|
|
1009 Check every system call for an error return, unless you know you wish to |
|
|
1010 ignore errors. Include the system error text (from @code{perror} or |
|
|
1011 equivalent) in @emph{every} error message resulting from a failing |
|
|
1012 system call, as well as the name of the file if any and the name of the |
|
|
1013 utility. Just ``cannot open foo.c'' or ``stat failed'' is not |
|
|
1014 sufficient. |
|
|
1015 |
|
|
1016 Check every call to @code{malloc} or @code{realloc} to see if it |
|
|
1017 returned zero. Check @code{realloc} even if you are making the block |
|
|
1018 smaller; in a system that rounds block sizes to a power of 2, |
|
|
1019 @code{realloc} may get a different block if you ask for less space. |
|
|
1020 |
|
|
1021 In Unix, @code{realloc} can destroy the storage block if it returns |
|
|
1022 zero. GNU @code{realloc} does not have this bug: if it fails, the |
|
|
1023 original block is unchanged. Feel free to assume the bug is fixed. If |
|
|
1024 you wish to run your program on Unix, and wish to avoid lossage in this |
|
|
1025 case, you can use the GNU @code{malloc}. |
|
|
1026 |
|
|
1027 You must expect @code{free} to alter the contents of the block that was |
|
|
1028 freed. Anything you want to fetch from the block, you must fetch before |
|
|
1029 calling @code{free}. |
|
|
1030 |
|
|
1031 If @code{malloc} fails in a noninteractive program, make that a fatal |
|
|
1032 error. In an interactive program (one that reads commands from the |
|
|
1033 user), it is better to abort the command and return to the command |
|
|
1034 reader loop. This allows the user to kill other processes to free up |
|
|
1035 virtual memory, and then try the command again. |
|
|
1036 |
|
|
1037 Use @code{getopt_long} to decode arguments, unless the argument syntax |
|
|
1038 makes this unreasonable. |
|
|
1039 |
|
|
1040 When static storage is to be written in during program execution, use |
|
|
1041 explicit C code to initialize it. Reserve C initialized declarations |
|
|
1042 for data that will not be changed. |
|
|
1043 |
|
|
1044 Try to avoid low-level interfaces to obscure Unix data structures (such |
|
|
1045 as file directories, utmp, or the layout of kernel memory), since these |
|
|
1046 are less likely to work compatibly. If you need to find all the files |
|
|
1047 in a directory, use @code{readdir} or some other high-level interface. |
|
|
1048 These will be supported compatibly by GNU. |
|
|
1049 |
|
|
1050 By default, the GNU system will provide the signal handling functions of |
|
|
1051 @sc{BSD} and of @sc{POSIX}. So GNU software should be written to use |
|
|
1052 these. |
|
|
1053 |
|
|
1054 In error checks that detect ``impossible'' conditions, just abort. |
|
|
1055 There is usually no point in printing any message. These checks |
|
|
1056 indicate the existence of bugs. Whoever wants to fix the bugs will have |
|
|
1057 to read the source code and run a debugger. So explain the problem with |
|
|
1058 comments in the source. The relevant data will be in variables, which |
|
|
1059 are easy to examine with the debugger, so there is no point moving them |
|
|
1060 elsewhere. |
|
|
1061 |
|
|
1062 |
|
|
1063 @node Errors |
|
|
1064 @chapter Formatting Error Messages |
|
|
1065 |
|
|
1066 Error messages from compilers should look like this: |
|
|
1067 |
|
|
1068 @example |
|
|
1069 @var{source-file-name}:@var{lineno}: @var{message} |
|
|
1070 @end example |
|
|
1071 |
|
|
1072 Error messages from other noninteractive programs should look like this: |
|
|
1073 |
|
|
1074 @example |
|
|
1075 @var{program}:@var{source-file-name}:@var{lineno}: @var{message} |
|
|
1076 @end example |
|
|
1077 |
|
|
1078 @noindent |
|
|
1079 when there is an appropriate source file, or like this: |
|
|
1080 |
|
|
1081 @example |
|
|
1082 @var{program}: @var{message} |
|
|
1083 @end example |
|
|
1084 |
|
|
1085 @noindent |
|
|
1086 when there is no relevant source file. |
|
|
1087 |
|
|
1088 In an interactive program (one that is reading commands from a |
|
|
1089 terminal), it is better not to include the program name in an error |
|
|
1090 message. The place to indicate which program is running is in the |
|
|
1091 prompt or with the screen layout. (When the same program runs with |
|
|
1092 input from a source other than a terminal, it is not interactive and |
|
|
1093 would do best to print error messages using the noninteractive style.) |
|
|
1094 |
|
|
1095 The string @var{message} should not begin with a capital letter when |
|
|
1096 it follows a program name and/or filename. Also, it should not end |
|
|
1097 with a period. |
|
|
1098 |
|
|
1099 Error messages from interactive programs, and other messages such as |
|
|
1100 usage messages, should start with a capital letter. But they should not |
|
|
1101 end with a period. |
|
|
1102 |
|
|
1103 |
|
|
1104 @node Libraries |
|
|
1105 @chapter Library Behavior |
|
|
1106 |
|
|
1107 Try to make library functions reentrant. If they need to do dynamic |
|
|
1108 storage allocation, at least try to avoid any nonreentrancy aside from |
|
|
1109 that of @code{malloc} itself. |
|
|
1110 |
|
|
1111 Here are certain name conventions for libraries, to avoid name |
|
|
1112 conflicts. |
|
|
1113 |
|
|
1114 Choose a name prefix for the library, more than two characters long. |
|
|
1115 All external function and variable names should start with this |
|
|
1116 prefix. In addition, there should only be one of these in any given |
|
|
1117 library member. This usually means putting each one in a separate |
|
|
1118 source file. |
|
|
1119 |
|
|
1120 An exception can be made when two external symbols are always used |
|
|
1121 together, so that no reasonable program could use one without the |
|
|
1122 other; then they can both go in the same file. |
|
|
1123 |
|
|
1124 External symbols that are not documented entry points for the user |
|
|
1125 should have names beginning with @samp{_}. They should also contain |
|
|
1126 the chosen name prefix for the library, to prevent collisions with |
|
|
1127 other libraries. These can go in the same files with user entry |
|
|
1128 points if you like. |
|
|
1129 |
|
|
1130 Static functions and variables can be used as you like and need not |
|
|
1131 fit any naming convention. |
|
|
1132 |
|
|
1133 |
|
|
1134 @node Portability |
|
|
1135 @chapter Portability As It Applies to GNU |
|
|
1136 |
|
|
1137 Much of what is called ``portability'' in the Unix world refers to |
|
|
1138 porting to different Unix versions. This is a secondary consideration |
|
|
1139 for GNU software, because its primary purpose is to run on top of one |
|
|
1140 and only one kernel, the GNU kernel, compiled with one and only one C |
|
|
1141 compiler, the GNU C compiler. The amount and kinds of variation among |
|
|
1142 GNU systems on different cpu's will be like the variation among Berkeley |
|
|
1143 4.3 systems on different cpu's. |
|
|
1144 |
|
|
1145 All users today run GNU software on non-GNU systems. So supporting a |
|
|
1146 variety of non-GNU systems is desirable; simply not paramount. |
|
|
1147 The easiest way to achieve portability to a reasonable range of systems |
|
|
1148 is to use Autoconf. It's unlikely that your program needs to know more |
|
|
1149 information about the host machine than Autoconf can provide, simply |
|
|
1150 because most of the programs that need such knowledge have already been |
|
|
1151 written. |
|
|
1152 |
|
|
1153 It is difficult to be sure exactly what facilities the GNU kernel |
|
|
1154 will provide, since it isn't finished yet. Therefore, assume you can |
|
|
1155 use anything in 4.3; just avoid using the format of semi-internal data |
|
|
1156 bases (e.g., directories) when there is a higher-level alternative |
|
|
1157 (@code{readdir}). |
|
|
1158 |
|
|
1159 You can freely assume any reasonably standard facilities in the C |
|
|
1160 language, libraries or kernel, because we will find it necessary to |
|
|
1161 support these facilities in the full GNU system, whether or not we |
|
|
1162 have already done so. The fact that there may exist kernels or C |
|
|
1163 compilers that lack these facilities is irrelevant as long as the GNU |
|
|
1164 kernel and C compiler support them. |
|
|
1165 |
|
|
1166 It remains necessary to worry about differences among cpu types, such |
|
|
1167 as the difference in byte ordering and alignment restrictions. It's |
|
|
1168 unlikely that 16-bit machines will ever be supported by GNU, so there |
|
|
1169 is no point in spending any time to consider the possibility that an |
|
|
1170 int will be less than 32 bits. |
|
|
1171 |
|
|
1172 You can assume that all pointers have the same format, regardless |
|
|
1173 of the type they point to, and that this is really an integer. |
|
|
1174 There are some weird machines where this isn't true, but they aren't |
|
|
1175 important; don't waste time catering to them. Besides, eventually |
|
|
1176 we will put function prototypes into all GNU programs, and that will |
|
|
1177 probably make your program work even on weird machines. |
|
|
1178 |
|
|
1179 Since some important machines (including the 68000) are big-endian, |
|
|
1180 it is important not to assume that the address of an @code{int} object |
|
|
1181 is also the address of its least-significant byte. Thus, don't |
|
|
1182 make the following mistake: |
|
|
1183 |
|
|
1184 @example |
|
|
1185 int c; |
|
|
1186 @dots{} |
|
|
1187 while ((c = getchar()) != EOF) |
|
|
1188 write(file_descriptor, &c, 1); |
|
|
1189 @end example |
|
|
1190 |
|
|
1191 You can assume that it is reasonable to use a meg of memory. Don't |
|
|
1192 strain to reduce memory usage unless it can get to that level. If |
|
|
1193 your program creates complicated data structures, just make them in |
|
|
1194 core and give a fatal error if malloc returns zero. |
|
|
1195 |
|
|
1196 If a program works by lines and could be applied to arbitrary |
|
|
1197 user-supplied input files, it should keep only a line in memory, because |
|
|
1198 this is not very hard and users will want to be able to operate on input |
|
|
1199 files that are bigger than will fit in core all at once. |
|
|
1200 |
|
|
1201 |
|
|
1202 @node User Interfaces |
|
|
1203 @chapter Standards for Command Line Interfaces |
|
|
1204 |
|
|
1205 Please don't make the behavior of a utility depend on the name used |
|
|
1206 to invoke it. It is useful sometimes to make a link to a utility |
|
|
1207 with a different name, and that should not change what it does. |
|
|
1208 |
|
|
1209 Instead, use a run time option or a compilation switch or both |
|
|
1210 to select among the alternate behaviors. |
|
|
1211 |
|
|
1212 Likewise, please don't make the behavior of the program depend on the |
|
|
1213 type of output device it is used with. Device independence is an |
|
|
1214 important principle of the system's design; do not compromise it |
|
|
1215 merely to save someone from typing an option now and then. |
|
|
1216 |
|
|
1217 If you think one behavior is most useful when the output is to a |
|
|
1218 terminal, and another is most useful when the output is a file or a |
|
|
1219 pipe, then it is usually best to make the default behavior the one that |
|
|
1220 is useful with output to a terminal, and have an option for the other |
|
|
1221 behavior. |
|
|
1222 |
|
|
1223 Compatibility requires certain programs to depend on the type of output |
|
|
1224 device. It would be disastrous if @code{ls} or @code{sh} did not do so |
|
|
1225 in the way all users expect. In some of these cases, we supplement the |
|
|
1226 program with a preferred alternate version that does not depend on the |
|
|
1227 output device type. For example, we provide a @code{dir} program much |
|
|
1228 like @code{ls} except that its default output format is always |
|
|
1229 multi-column format. |
|
|
1230 |
|
|
1231 It is a good idea to follow the @sc{POSIX} guidelines for the |
|
|
1232 command-line options of a program. The easiest way to do this is to use |
|
|
1233 @code{getopt} to parse them. Note that the GNU version of @code{getopt} |
|
|
1234 will normally permit options anywhere among the arguments unless the |
|
|
1235 special argument @samp{--} is used. This is not what @sc{POSIX} |
|
|
1236 specifies; it is a GNU extension. |
|
|
1237 |
|
|
1238 Please define long-named options that are equivalent to the |
|
|
1239 single-letter Unix-style options. We hope to make GNU more user |
|
|
1240 friendly this way. This is easy to do with the GNU function |
|
|
1241 @code{getopt_long}. |
|
|
1242 |
|
|
1243 One of the advantages of long-named options is that they can be |
|
|
1244 consistent from program to program. For example, users should be able |
|
|
1245 to expect the ``verbose'' option of any GNU program which has one, to be |
|
|
1246 spelled precisely @samp{--verbose}. To achieve this uniformity, look at |
|
|
1247 the table of common long-option names when you choose the option names |
|
|
1248 for your program. The table appears below. |
|
|
1249 |
|
|
1250 If you use names not already in the table, please send |
|
|
1251 @samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we |
|
|
1252 can update the table. |
|
|
1253 |
|
|
1254 It is usually a good idea for file names given as ordinary arguments |
|
|
1255 to be input files only; any output files would be specified using |
|
|
1256 options (preferably @samp{-o}). Even if you allow an output file name |
|
|
1257 as an ordinary argument for compatibility, try to provide a suitable |
|
|
1258 option as well. This will lead to more consistency among GNU |
|
|
1259 utilities, so that there are fewer idiosyncracies for users to |
|
|
1260 remember. |
|
|
1261 |
|
|
1262 Programs should support an option @samp{--version} which prints the |
|
|
1263 program's version number on standard output and exits successfully, and |
|
|
1264 an option @samp{--help} which prints option usage information on |
|
|
1265 standard output and exits successfully. These options should inhibit |
|
|
1266 the normal function of the command; they should do nothing except print |
|
|
1267 the requested information. |
|
|
1268 |
|
|
1269 @c Please leave newlines between items in this table; it's much easier |
|
|
1270 @c to update when it isn't completely squashed together and unreadable. |
|
|
1271 @c When there is more than one short option for a long option name, put |
|
|
1272 @c a semicolon between the lists of the programs that use them, not a |
|
|
1273 @c period. --friedman |
|
|
1274 |
|
|
1275 @table @samp |
|
|
1276 |
|
|
1277 @item after-date |
|
|
1278 @samp{-N} in @code{tar}. |
|
|
1279 |
|
|
1280 @item all |
|
|
1281 @samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, |
|
|
1282 and @code{unexpand}. |
|
|
1283 |
|
|
1284 @item all-text |
|
|
1285 @samp{-a} in @code{diff}. |
|
|
1286 |
|
|
1287 @item almost-all |
|
|
1288 @samp{-A} in @code{ls}. |
|
|
1289 |
|
|
1290 @item append |
|
|
1291 @samp{-a} in @code{etags}, @code{tee}, @code{time}; |
|
|
1292 @samp{-r} in @code{tar}. |
|
|
1293 |
|
|
1294 @item archive |
|
|
1295 @samp{-a} in @code{cp}. |
|
|
1296 |
|
|
1297 @item archive-name |
|
|
1298 @samp{-n} in @code{shar}. |
|
|
1299 |
|
|
1300 @item arglength |
|
|
1301 @samp{-l} in @code{m4}. |
|
|
1302 |
|
|
1303 @item ascii |
|
|
1304 @samp{-a} in @code{diff}. |
|
|
1305 |
|
|
1306 @item assume-new |
|
|
1307 @samp{-W} in Make. |
|
|
1308 |
|
|
1309 @item assume-old |
|
|
1310 @samp{-o} in Make. |
|
|
1311 |
|
|
1312 @item auto-check |
|
|
1313 @samp{-a} in @code{recode}. |
|
|
1314 |
|
|
1315 @item auto-pager |
|
|
1316 @samp{-a} in @code{wdiff}. |
|
|
1317 |
|
|
1318 @item auto-reference |
|
|
1319 @samp{-A} in @code{ptx}. |
|
|
1320 |
|
|
1321 @item avoid-wraps |
|
|
1322 @samp{-n} in @code{wdiff}. |
|
|
1323 |
|
|
1324 @item backward-search |
|
|
1325 @samp{-B} in @code{ctags}. |
|
|
1326 |
|
|
1327 @item basename |
|
|
1328 @samp{-f} in @code{shar}. |
|
|
1329 |
|
|
1330 @item batch |
|
|
1331 Used in GDB. |
|
|
1332 |
|
|
1333 @item baud |
|
|
1334 Used in GDB. |
|
|
1335 |
|
|
1336 @item before |
|
|
1337 @samp{-b} in @code{tac}. |
|
|
1338 |
|
|
1339 @item binary |
|
|
1340 @samp{-b} in @code{cpio} and @code{diff}. |
|
|
1341 |
|
|
1342 @item bits-per-code |
|
|
1343 @samp{-b} in @code{shar}. |
|
|
1344 |
|
|
1345 @item block-size |
|
|
1346 Used in @code{cpio} and @code{tar}. |
|
|
1347 |
|
|
1348 @item blocks |
|
|
1349 @samp{-b} in @code{head} and @code{tail}. |
|
|
1350 |
|
|
1351 @item break-file |
|
|
1352 @samp{-b} in @code{ptx}. |
|
|
1353 |
|
|
1354 @item brief |
|
|
1355 Used in various programs to make output shorter. |
|
|
1356 |
|
|
1357 @item bytes |
|
|
1358 @samp{-c} in @code{head}, @code{split}, and @code{tail}. |
|
|
1359 |
|
|
1360 @item c@t{++} |
|
|
1361 @samp{-C} in @code{etags}. |
|
|
1362 |
|
|
1363 @item catenate |
|
|
1364 @samp{-A} in @code{tar}. |
|
|
1365 |
|
|
1366 @item cd |
|
|
1367 Used in various programs to specify the directory to use. |
|
|
1368 |
|
|
1369 @item changes |
|
|
1370 @samp{-c} in @code{chgrp} and @code{chown}. |
|
|
1371 |
|
|
1372 @item classify |
|
|
1373 @samp{-F} in @code{ls}. |
|
|
1374 |
|
|
1375 @item colons |
|
|
1376 @samp{-c} in @code{recode}. |
|
|
1377 |
|
|
1378 @item command |
|
|
1379 @samp{-c} in @code{su}; |
|
|
1380 @samp{-x} in GDB. |
|
|
1381 |
|
|
1382 @item compare |
|
|
1383 @samp{-d} in @code{tar}. |
|
|
1384 |
|
|
1385 @item compress |
|
|
1386 @samp{-Z} in @code{tar} and @code{shar}. |
|
|
1387 |
|
|
1388 @item concatenate |
|
|
1389 @samp{-A} in @code{tar}. |
|
|
1390 |
|
|
1391 @item confirmation |
|
|
1392 @samp{-w} in @code{tar}. |
|
|
1393 |
|
|
1394 @item context |
|
|
1395 Used in @code{diff}. |
|
|
1396 |
|
|
1397 @item copyright |
|
|
1398 @samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}. |
|
|
1399 |
|
|
1400 @item core |
|
|
1401 Used in GDB. |
|
|
1402 |
|
|
1403 @item count |
|
|
1404 @samp{-q} in @code{who}. |
|
|
1405 |
|
|
1406 @item count-links |
|
|
1407 @samp{-l} in @code{du}. |
|
|
1408 |
|
|
1409 @item create |
|
|
1410 Used in @code{tar} and @code{cpio}. |
|
|
1411 |
|
|
1412 @item cut-mark |
|
|
1413 @samp{-c} in @code{shar}. |
|
|
1414 |
|
|
1415 @item cxref |
|
|
1416 @samp{-x} in @code{ctags}. |
|
|
1417 |
|
|
1418 @item date |
|
|
1419 @samp{-d} in @code{touch}. |
|
|
1420 |
|
|
1421 @item debug |
|
|
1422 @samp{-d} in Make and @code{m4}; |
|
|
1423 @samp{-t} in Bison. |
|
|
1424 |
|
|
1425 @item define |
|
|
1426 @samp{-D} in @code{m4}. |
|
|
1427 |
|
|
1428 @item defines |
|
|
1429 @samp{-d} in Bison and @code{ctags}. |
|
|
1430 |
|
|
1431 @item delete |
|
|
1432 @samp{-D} in @code{tar}. |
|
|
1433 |
|
|
1434 @item dereference |
|
|
1435 @samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, |
|
|
1436 @code{ls}, and @code{tar}. |
|
|
1437 |
|
|
1438 @item dereference-args |
|
|
1439 @samp{-D} in @code{du}. |
|
|
1440 |
|
|
1441 @item diacritics |
|
|
1442 @samp{-d} in @code{recode}. |
|
|
1443 |
|
|
1444 @item dictionary-order |
|
|
1445 @samp{-d} in @code{look}. |
|
|
1446 |
|
|
1447 @item diff |
|
|
1448 @samp{-d} in @code{tar}. |
|
|
1449 |
|
|
1450 @item digits |
|
|
1451 @samp{-n} in @code{csplit}. |
|
|
1452 |
|
|
1453 @item directory |
|
|
1454 Specify the directory to use, in various programs. In @code{ls}, it |
|
|
1455 means to show directories themselves rather than their contents. In |
|
|
1456 @code{rm} and @code{ln}, it means to not treat links to directories |
|
|
1457 specially. |
|
|
1458 |
|
|
1459 @item discard-all |
|
|
1460 @samp{-x} in @code{strip}. |
|
|
1461 |
|
|
1462 @item discard-locals |
|
|
1463 @samp{-X} in @code{strip}. |
|
|
1464 |
|
|
1465 @item dry-run |
|
|
1466 @samp{-n} in Make. |
|
|
1467 |
|
|
1468 @item ed |
|
|
1469 @samp{-e} in @code{diff}. |
|
|
1470 |
|
|
1471 @item elide-empty-files |
|
|
1472 @samp{-z} in @code{csplit}. |
|
|
1473 |
|
|
1474 @item end-delete |
|
|
1475 @samp{-x} in @code{wdiff}. |
|
|
1476 |
|
|
1477 @item end-insert |
|
|
1478 @samp{-z} in @code{wdiff}. |
|
|
1479 |
|
|
1480 @item entire-new-file |
|
|
1481 @samp{-N} in @code{diff}. |
|
|
1482 |
|
|
1483 @item environment-overrides |
|
|
1484 @samp{-e} in Make. |
|
|
1485 |
|
|
1486 @item eof |
|
|
1487 @samp{-e} in @code{xargs}. |
|
|
1488 |
|
|
1489 @item epoch |
|
|
1490 Used in GDB. |
|
|
1491 |
|
|
1492 @item error-limit |
|
|
1493 Used in Makeinfo. |
|
|
1494 |
|
|
1495 @item error-output |
|
|
1496 @samp{-o} in @code{m4}. |
|
|
1497 |
|
|
1498 @item escape |
|
|
1499 @samp{-b} in @code{ls}. |
|
|
1500 |
|
|
1501 @item exclude-from |
|
|
1502 @samp{-X} in @code{tar}. |
|
|
1503 |
|
|
1504 @item exec |
|
|
1505 Used in GDB. |
|
|
1506 |
|
|
1507 @item exit |
|
|
1508 @samp{-x} in @code{xargs}. |
|
|
1509 |
|
|
1510 @item exit-0 |
|
|
1511 @samp{-e} in @code{unshar}. |
|
|
1512 |
|
|
1513 @item expand-tabs |
|
|
1514 @samp{-t} in @code{diff}. |
|
|
1515 |
|
|
1516 @item expression |
|
|
1517 @samp{-e} in @code{sed}. |
|
|
1518 |
|
|
1519 @item extern-only |
|
|
1520 @samp{-g} in @code{nm}. |
|
|
1521 |
|
|
1522 @item extract |
|
|
1523 @samp{-i} in @code{cpio}; |
|
|
1524 @samp{-x} in @code{tar}. |
|
|
1525 |
|
|
1526 @item faces |
|
|
1527 @samp{-f} in @code{finger}. |
|
|
1528 |
|
|
1529 @item fast |
|
|
1530 @samp{-f} in @code{su}. |
|
|
1531 |
|
|
1532 @item fatal-warnings |
|
|
1533 @samp{-E} in @code{m4}. |
|
|
1534 |
|
|
1535 @item file |
|
|
1536 @samp{-f} in @code{info}, Make, @code{mt}, and @code{tar}; |
|
|
1537 @samp{-n} in @code{sed}; |
|
|
1538 @samp{-r} in @code{touch}. |
|
|
1539 |
|
|
1540 @item file-prefix |
|
|
1541 @samp{-b} in Bison. |
|
|
1542 |
|
|
1543 @item file-type |
|
|
1544 @samp{-F} in @code{ls}. |
|
|
1545 |
|
|
1546 @item files-from |
|
|
1547 @samp{-T} in @code{tar}. |
|
|
1548 |
|
|
1549 @item fill-column |
|
|
1550 Used in Makeinfo. |
|
|
1551 |
|
|
1552 @item flag-truncation |
|
|
1553 @samp{-F} in @code{ptx}. |
|
|
1554 |
|
|
1555 @item fixed-output-files |
|
|
1556 @samp{-y} in Bison. |
|
|
1557 |
|
|
1558 @item follow |
|
|
1559 @samp{-f} in @code{tail}. |
|
|
1560 |
|
|
1561 @item footnote-style |
|
|
1562 Used in Makeinfo. |
|
|
1563 |
|
|
1564 @item force |
|
|
1565 @samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. |
|
|
1566 |
|
|
1567 @item force-prefix |
|
|
1568 @samp{-F} in @code{shar}. |
|
|
1569 |
|
|
1570 @item format |
|
|
1571 Used in @code{ls}, @code{time}, and @code{ptx}. |
|
|
1572 |
|
|
1573 @item freeze-state |
|
|
1574 @samp{-F} in @code{m4}. |
|
|
1575 |
|
|
1576 @item fullname |
|
|
1577 Used in GDB. |
|
|
1578 |
|
|
1579 @item gap-size |
|
|
1580 @samp{-g} in @code{ptx}. |
|
|
1581 |
|
|
1582 @item get |
|
|
1583 @samp{-x} in @code{tar}. |
|
|
1584 |
|
|
1585 @item graphic |
|
|
1586 @samp{-i} in @code{ul}. |
|
|
1587 |
|
|
1588 @item graphics |
|
|
1589 @samp{-g} in @code{recode}. |
|
|
1590 |
|
|
1591 @item group |
|
|
1592 @samp{-g} in @code{install}. |
|
|
1593 |
|
|
1594 @item gzip |
|
|
1595 @samp{-z} in @code{tar} and @code{shar}. |
|
|
1596 |
|
|
1597 @item hashsize |
|
|
1598 @samp{-H} in @code{m4}. |
|
|
1599 |
|
|
1600 @item header |
|
|
1601 @samp{-h} in @code{objdump} and @code{recode} |
|
|
1602 |
|
|
1603 @item heading |
|
|
1604 @samp{-H} in @code{who}. |
|
|
1605 |
|
|
1606 @item help |
|
|
1607 Used to ask for brief usage information. |
|
|
1608 |
|
|
1609 @item here-delimiter |
|
|
1610 @samp{-d} in @code{shar}. |
|
|
1611 |
|
|
1612 @item hide-control-chars |
|
|
1613 @samp{-q} in @code{ls}. |
|
|
1614 |
|
|
1615 @item idle |
|
|
1616 @samp{-u} in @code{who}. |
|
|
1617 |
|
|
1618 @item ifdef |
|
|
1619 @samp{-D} in @code{diff}. |
|
|
1620 |
|
|
1621 @item ignore |
|
|
1622 @samp{-I} in @code{ls}; |
|
|
1623 @samp{-x} in @code{recode}. |
|
|
1624 |
|
|
1625 @item ignore-all-space |
|
|
1626 @samp{-w} in @code{diff}. |
|
|
1627 |
|
|
1628 @item ignore-backups |
|
|
1629 @samp{-B} in @code{ls}. |
|
|
1630 |
|
|
1631 @item ignore-blank-lines |
|
|
1632 @samp{-B} in @code{diff}. |
|
|
1633 |
|
|
1634 @item ignore-case |
|
|
1635 @samp{-f} in @code{look} and @code{ptx}; |
|
|
1636 @samp{-i} in @code{diff} and @code{wdiff}. |
|
|
1637 |
|
|
1638 @item ignore-errors |
|
|
1639 @samp{-i} in Make. |
|
|
1640 |
|
|
1641 @item ignore-file |
|
|
1642 @samp{-i} in @code{ptx}. |
|
|
1643 |
|
|
1644 @item ignore-indentation |
|
|
1645 @samp{-S} in @code{etags}. |
|
|
1646 |
|
|
1647 @item ignore-init-file |
|
|
1648 @samp{-f} in Oleo. |
|
|
1649 |
|
|
1650 @item ignore-interrupts |
|
|
1651 @samp{-i} in @code{tee}. |
|
|
1652 |
|
|
1653 @item ignore-matching-lines |
|
|
1654 @samp{-I} in @code{diff}. |
|
|
1655 |
|
|
1656 @item ignore-space-change |
|
|
1657 @samp{-b} in @code{diff}. |
|
|
1658 |
|
|
1659 @item ignore-zeros |
|
|
1660 @samp{-i} in @code{tar}. |
|
|
1661 |
|
|
1662 @item include |
|
|
1663 @samp{-i} in @code{etags}; |
|
|
1664 @samp{-I} in @code{m4}. |
|
|
1665 |
|
|
1666 @item include-dir |
|
|
1667 @samp{-I} in Make. |
|
|
1668 |
|
|
1669 @item incremental |
|
|
1670 @samp{-G} in @code{tar}. |
|
|
1671 |
|
|
1672 @item info |
|
|
1673 @samp{-i}, @samp{-l}, and @samp{-m} in Finger. |
|
|
1674 |
|
|
1675 @item initial |
|
|
1676 @samp{-i} in @code{expand}. |
|
|
1677 |
|
|
1678 @item initial-tab |
|
|
1679 @samp{-T} in @code{diff}. |
|
|
1680 |
|
|
1681 @item inode |
|
|
1682 @samp{-i} in @code{ls}. |
|
|
1683 |
|
|
1684 @item interactive |
|
|
1685 @samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; |
|
|
1686 @samp{-e} in @code{m4}; |
|
|
1687 @samp{-p} in @code{xargs}; |
|
|
1688 @samp{-w} in @code{tar}. |
|
|
1689 |
|
|
1690 @item intermix-type |
|
|
1691 @samp{-p} in @code{shar}. |
|
|
1692 |
|
|
1693 @item jobs |
|
|
1694 @samp{-j} in Make. |
|
|
1695 |
|
|
1696 @item just-print |
|
|
1697 @samp{-n} in Make. |
|
|
1698 |
|
|
1699 @item keep-going |
|
|
1700 @samp{-k} in Make. |
|
|
1701 |
|
|
1702 @item keep-files |
|
|
1703 @samp{-k} in @code{csplit}. |
|
|
1704 |
|
|
1705 @item kilobytes |
|
|
1706 @samp{-k} in @code{du} and @code{ls}. |
|
|
1707 |
|
|
1708 @item language |
|
|
1709 @samp{-l} in @code{etags}. |
|
|
1710 |
|
|
1711 @item less-mode |
|
|
1712 @samp{-l} in @code{wdiff}. |
|
|
1713 |
|
|
1714 @item level-for-gzip |
|
|
1715 @samp{-g} in @code{shar}. |
|
|
1716 |
|
|
1717 @item line-bytes |
|
|
1718 @samp{-C} in @code{split}. |
|
|
1719 |
|
|
1720 @item lines |
|
|
1721 Used in @code{split}, @code{head}, and @code{tail}. |
|
|
1722 |
|
|
1723 @item link |
|
|
1724 @samp{-l} in @code{cpio}. |
|
|
1725 |
|
|
1726 @item list |
|
|
1727 @samp{-t} in @code{cpio}; |
|
|
1728 @samp{-l} in @code{recode}. |
|
|
1729 |
|
|
1730 @item list |
|
|
1731 @samp{-t} in @code{tar}. |
|
|
1732 |
|
|
1733 @item literal |
|
|
1734 @samp{-N} in @code{ls}. |
|
|
1735 |
|
|
1736 @item load-average |
|
|
1737 @samp{-l} in Make. |
|
|
1738 |
|
|
1739 @item login |
|
|
1740 Used in @code{su}. |
|
|
1741 |
|
|
1742 @item machine |
|
|
1743 No listing of which programs already use this; |
|
|
1744 someone should check to |
|
|
1745 see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. |
|
|
1746 |
|
|
1747 @item macro-name |
|
|
1748 @samp{-M} in @code{ptx}. |
|
|
1749 |
|
|
1750 @item mail |
|
|
1751 @samp{-m} in @code{hello} and @code{uname}. |
|
|
1752 |
|
|
1753 @item make-directories |
|
|
1754 @samp{-d} in @code{cpio}. |
|
|
1755 |
|
|
1756 @item makefile |
|
|
1757 @samp{-f} in Make. |
|
|
1758 |
|
|
1759 @item mapped |
|
|
1760 Used in GDB. |
|
|
1761 |
|
|
1762 @item max-args |
|
|
1763 @samp{-n} in @code{xargs}. |
|
|
1764 |
|
|
1765 @item max-chars |
|
|
1766 @samp{-n} in @code{xargs}. |
|
|
1767 |
|
|
1768 @item max-lines |
|
|
1769 @samp{-l} in @code{xargs}. |
|
|
1770 |
|
|
1771 @item max-load |
|
|
1772 @samp{-l} in Make. |
|
|
1773 |
|
|
1774 @item max-procs |
|
|
1775 @samp{-P} in @code{xargs}. |
|
|
1776 |
|
|
1777 @item mesg |
|
|
1778 @samp{-T} in @code{who}. |
|
|
1779 |
|
|
1780 @item message |
|
|
1781 @samp{-T} in @code{who}. |
|
|
1782 |
|
|
1783 @item minimal |
|
|
1784 @samp{-d} in @code{diff}. |
|
|
1785 |
|
|
1786 @item mixed-uuencode |
|
|
1787 @samp{-M} in @code{shar}. |
|
|
1788 |
|
|
1789 @item mode |
|
|
1790 @samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. |
|
|
1791 |
|
|
1792 @item modification-time |
|
|
1793 @samp{-m} in @code{tar}. |
|
|
1794 |
|
|
1795 @item multi-volume |
|
|
1796 @samp{-M} in @code{tar}. |
|
|
1797 |
|
|
1798 @item name-prefix |
|
|
1799 @samp{-a} in Bison. |
|
|
1800 |
|
|
1801 @item nesting-limit |
|
|
1802 @samp{-L} in @code{m4}. |
|
|
1803 |
|
|
1804 @item net-headers |
|
|
1805 @samp{-a} in @code{shar}. |
|
|
1806 |
|
|
1807 @item new-file |
|
|
1808 @samp{-W} in Make. |
|
|
1809 |
|
|
1810 @item no-builtin-rules |
|
|
1811 @samp{-r} in Make. |
|
|
1812 |
|
|
1813 @item no-character-count |
|
|
1814 @samp{-w} in @code{shar}. |
|
|
1815 |
|
|
1816 @item no-check-existing |
|
|
1817 @samp{-x} in @code{shar}. |
|
|
1818 |
|
|
1819 @item no-common |
|
|
1820 @samp{-3} in @code{wdiff}. |
|
|
1821 |
|
|
1822 @item no-create |
|
|
1823 @samp{-c} in @code{touch}. |
|
|
1824 |
|
|
1825 @item no-defines |
|
|
1826 @samp{-D} in @code{etags}. |
|
|
1827 |
|
|
1828 @item no-deleted |
|
|
1829 @samp{-1} in @code{wdiff}. |
|
|
1830 |
|
|
1831 @item no-dereference |
|
|
1832 @samp{-d} in @code{cp}. |
|
|
1833 |
|
|
1834 @item no-inserted |
|
|
1835 @samp{-2} in @code{wdiff}. |
|
|
1836 |
|
|
1837 @item no-keep-going |
|
|
1838 @samp{-S} in Make. |
|
|
1839 |
|
|
1840 @item no-lines |
|
|
1841 @samp{-l} in Bison. |
|
|
1842 |
|
|
1843 @item no-piping |
|
|
1844 @samp{-P} in @code{shar}. |
|
|
1845 |
|
|
1846 @item no-prof |
|
|
1847 @samp{-e} in @code{gprof}. |
|
|
1848 |
|
|
1849 @item no-regex |
|
|
1850 @samp{-R} in @code{etags}. |
|
|
1851 |
|
|
1852 @item no-sort |
|
|
1853 @samp{-p} in @code{nm}. |
|
|
1854 |
|
|
1855 @item no-split |
|
|
1856 Used in Makeinfo. |
|
|
1857 |
|
|
1858 @item no-static |
|
|
1859 @samp{-a} in @code{gprof}. |
|
|
1860 |
|
|
1861 @item no-time |
|
|
1862 @samp{-E} in @code{gprof}. |
|
|
1863 |
|
|
1864 @item no-timestamp |
|
|
1865 @samp{-m} in @code{shar}. |
|
|
1866 |
|
|
1867 @item no-validate |
|
|
1868 Used in Makeinfo. |
|
|
1869 |
|
|
1870 @item no-warn |
|
|
1871 Used in various programs to inhibit warnings. |
|
|
1872 |
|
|
1873 @item node |
|
|
1874 @samp{-n} in @code{info}. |
|
|
1875 |
|
|
1876 @item nodename |
|
|
1877 @samp{-n} in @code{uname}. |
|
|
1878 |
|
|
1879 @item nonmatching |
|
|
1880 @samp{-f} in @code{cpio}. |
|
|
1881 |
|
|
1882 @item nstuff |
|
|
1883 @samp{-n} in @code{objdump}. |
|
|
1884 |
|
|
1885 @item null |
|
|
1886 @samp{-0} in @code{xargs}. |
|
|
1887 |
|
|
1888 @item number |
|
|
1889 @samp{-n} in @code{cat}. |
|
|
1890 |
|
|
1891 @item number-nonblank |
|
|
1892 @samp{-b} in @code{cat}. |
|
|
1893 |
|
|
1894 @item numeric-sort |
|
|
1895 @samp{-n} in @code{nm}. |
|
|
1896 |
|
|
1897 @item numeric-uid-gid |
|
|
1898 @samp{-n} in @code{cpio} and @code{ls}. |
|
|
1899 |
|
|
1900 @item nx |
|
|
1901 Used in GDB. |
|
|
1902 |
|
|
1903 @item old-archive |
|
|
1904 @samp{-o} in @code{tar}. |
|
|
1905 |
|
|
1906 @item old-file |
|
|
1907 @samp{-o} in Make. |
|
|
1908 |
|
|
1909 @item one-file-system |
|
|
1910 @samp{-l} in @code{tar}, @code{cp}, and @code{du}. |
|
|
1911 |
|
|
1912 @item only-file |
|
|
1913 @samp{-o} in @code{ptx}. |
|
|
1914 |
|
|
1915 @item only-prof |
|
|
1916 @samp{-f} in @code{gprof}. |
|
|
1917 |
|
|
1918 @item only-time |
|
|
1919 @samp{-F} in @code{gprof}. |
|
|
1920 |
|
|
1921 @item output |
|
|
1922 In various programs, specify the output file name. |
|
|
1923 |
|
|
1924 @item output-prefix |
|
|
1925 @samp{-o} in @code{shar}. |
|
|
1926 |
|
|
1927 @item override |
|
|
1928 @samp{-o} in @code{rm}. |
|
|
1929 |
|
|
1930 @item overwrite |
|
|
1931 @samp{-c} in @code{unshar}. |
|
|
1932 |
|
|
1933 @item owner |
|
|
1934 @samp{-o} in @code{install}. |
|
|
1935 |
|
|
1936 @item paginate |
|
|
1937 @samp{-l} in @code{diff}. |
|
|
1938 |
|
|
1939 @item paragraph-indent |
|
|
1940 Used in Makeinfo. |
|
|
1941 |
|
|
1942 @item parents |
|
|
1943 @samp{-p} in @code{mkdir} and @code{rmdir}. |
|
|
1944 |
|
|
1945 @item pass-all |
|
|
1946 @samp{-p} in @code{ul}. |
|
|
1947 |
|
|
1948 @item pass-through |
|
|
1949 @samp{-p} in @code{cpio}. |
|
|
1950 |
|
|
1951 @item port |
|
|
1952 @samp{-P} in @code{finger}. |
|
|
1953 |
|
|
1954 @item portability |
|
|
1955 @samp{-c} in @code{cpio} and @code{tar}. |
|
|
1956 |
|
|
1957 @item prefix-builtins |
|
|
1958 @samp{-P} in @code{m4}. |
|
|
1959 |
|
|
1960 @item prefix |
|
|
1961 @samp{-f} in @code{csplit}. |
|
|
1962 |
|
|
1963 @item preserve |
|
|
1964 Used in @code{tar} and @code{cp}. |
|
|
1965 |
|
|
1966 @item preserve-environment |
|
|
1967 @samp{-p} in @code{su}. |
|
|
1968 |
|
|
1969 @item preserve-modification-time |
|
|
1970 @samp{-m} in @code{cpio}. |
|
|
1971 |
|
|
1972 @item preserve-order |
|
|
1973 @samp{-s} in @code{tar}. |
|
|
1974 |
|
|
1975 @item preserve-permissions |
|
|
1976 @samp{-p} in @code{tar}. |
|
|
1977 |
|
|
1978 @item print |
|
|
1979 @samp{-l} in @code{diff}. |
|
|
1980 |
|
|
1981 @item print-chars |
|
|
1982 @samp{-L} in @code{cmp}. |
|
|
1983 |
|
|
1984 @item print-data-base |
|
|
1985 @samp{-p} in Make. |
|
|
1986 |
|
|
1987 @item print-directory |
|
|
1988 @samp{-w} in Make. |
|
|
1989 |
|
|
1990 @item print-file-name |
|
|
1991 @samp{-o} in @code{nm}. |
|
|
1992 |
|
|
1993 @item print-symdefs |
|
|
1994 @samp{-s} in @code{nm}. |
|
|
1995 |
|
|
1996 @item printer |
|
|
1997 @samp{-p} in @code{wdiff}. |
|
|
1998 |
|
|
1999 @item query-user |
|
|
2000 @samp{-X} in @code{shar}. |
|
|
2001 |
|
|
2002 @item question |
|
|
2003 @samp{-q} in Make. |
|
|
2004 |
|
|
2005 @item quiet |
|
|
2006 Used in many programs to inhibit the usual output. @strong{Note:} every |
|
|
2007 program accepting @samp{--quiet} should accept @samp{--silent} as a |
|
|
2008 synonym. |
|
|
2009 |
|
|
2010 @item quiet-unshar |
|
|
2011 @samp{-Q} in @code{shar} |
|
|
2012 |
|
|
2013 @item quote-name |
|
|
2014 @samp{-Q} in @code{ls}. |
|
|
2015 |
|
|
2016 @item rcs |
|
|
2017 @samp{-n} in @code{diff}. |
|
|
2018 |
|
|
2019 @item read-full-blocks |
|
|
2020 @samp{-B} in @code{tar}. |
|
|
2021 |
|
|
2022 @item readnow |
|
|
2023 Used in GDB. |
|
|
2024 |
|
|
2025 @item recon |
|
|
2026 @samp{-n} in Make. |
|
|
2027 |
|
|
2028 @item record-number |
|
|
2029 @samp{-R} in @code{tar}. |
|
|
2030 |
|
|
2031 @item recursive |
|
|
2032 Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, |
|
|
2033 and @code{rm}. |
|
|
2034 |
|
|
2035 @item reference-limit |
|
|
2036 Used in Makeinfo. |
|
|
2037 |
|
|
2038 @item references |
|
|
2039 @samp{-r} in @code{ptx}. |
|
|
2040 |
|
|
2041 @item regex |
|
|
2042 @samp{-r} in @code{tac} and @code{etags}. |
|
|
2043 |
|
|
2044 @item release |
|
|
2045 @samp{-r} in @code{uname}. |
|
|
2046 |
|
|
2047 @item reload-state |
|
|
2048 @samp{-R} in @code{m4}. |
|
|
2049 |
|
|
2050 @item relocation |
|
|
2051 @samp{-r} in @code{objdump}. |
|
|
2052 |
|
|
2053 @item rename |
|
|
2054 @samp{-r} in @code{cpio}. |
|
|
2055 |
|
|
2056 @item replace |
|
|
2057 @samp{-i} in @code{xargs}. |
|
|
2058 |
|
|
2059 @item report-identical-files |
|
|
2060 @samp{-s} in @code{diff}. |
|
|
2061 |
|
|
2062 @item reset-access-time |
|
|
2063 @samp{-a} in @code{cpio}. |
|
|
2064 |
|
|
2065 @item reverse |
|
|
2066 @samp{-r} in @code{ls} and @code{nm}. |
|
|
2067 |
|
|
2068 @item reversed-ed |
|
|
2069 @samp{-f} in @code{diff}. |
|
|
2070 |
|
|
2071 @item right-side-defs |
|
|
2072 @samp{-R} in @code{ptx}. |
|
|
2073 |
|
|
2074 @item same-order |
|
|
2075 @samp{-s} in @code{tar}. |
|
|
2076 |
|
|
2077 @item same-permissions |
|
|
2078 @samp{-p} in @code{tar}. |
|
|
2079 |
|
|
2080 @item save |
|
|
2081 @samp{-g} in @code{stty}. |
|
|
2082 |
|
|
2083 @item se |
|
|
2084 Used in GDB. |
|
|
2085 |
|
|
2086 @item sentence-regexp |
|
|
2087 @samp{-S} in @code{ptx}. |
|
|
2088 |
|
|
2089 @item separate-dirs |
|
|
2090 @samp{-S} in @code{du}. |
|
|
2091 |
|
|
2092 @item separator |
|
|
2093 @samp{-s} in @code{tac}. |
|
|
2094 |
|
|
2095 @item sequence |
|
|
2096 Used by @code{recode} to chose files or pipes for sequencing passes. |
|
|
2097 |
|
|
2098 @item shell |
|
|
2099 @samp{-s} in @code{su}. |
|
|
2100 |
|
|
2101 @item show-all |
|
|
2102 @samp{-A} in @code{cat}. |
|
|
2103 |
|
|
2104 @item show-c-function |
|
|
2105 @samp{-p} in @code{diff}. |
|
|
2106 |
|
|
2107 @item show-ends |
|
|
2108 @samp{-E} in @code{cat}. |
|
|
2109 |
|
|
2110 @item show-function-line |
|
|
2111 @samp{-F} in @code{diff}. |
|
|
2112 |
|
|
2113 @item show-tabs |
|
|
2114 @samp{-T} in @code{cat}. |
|
|
2115 |
|
|
2116 @item silent |
|
|
2117 Used in many programs to inhibit the usual output. |
|
|
2118 @strong{Note:} every program accepting |
|
|
2119 @samp{--silent} should accept @samp{--quiet} as a synonym. |
|
|
2120 |
|
|
2121 @item size |
|
|
2122 @samp{-s} in @code{ls}. |
|
|
2123 |
|
|
2124 @item sort |
|
|
2125 Used in @code{ls}. |
|
|
2126 |
|
|
2127 @item sparse |
|
|
2128 @samp{-S} in @code{tar}. |
|
|
2129 |
|
|
2130 @item speed-large-files |
|
|
2131 @samp{-H} in @code{diff}. |
|
|
2132 |
|
|
2133 @item split-at |
|
|
2134 @samp{-E} in @code{unshar}. |
|
|
2135 |
|
|
2136 @item split-size-limit |
|
|
2137 @samp{-L} in @code{shar}. |
|
|
2138 |
|
|
2139 @item squeeze-blank |
|
|
2140 @samp{-s} in @code{cat}. |
|
|
2141 |
|
|
2142 @item start-delete |
|
|
2143 @samp{-w} in @code{wdiff}. |
|
|
2144 |
|
|
2145 @item start-insert |
|
|
2146 @samp{-y} in @code{wdiff}. |
|
|
2147 |
|
|
2148 @item starting-file |
|
|
2149 Used in @code{tar} and @code{diff} to specify which file within |
|
|
2150 a directory to start processing with. |
|
|
2151 |
|
|
2152 @item statistics |
|
|
2153 @samp{-s} in @code{wdiff}. |
|
|
2154 |
|
|
2155 @item stdin-file-list |
|
|
2156 @samp{-S} in @code{shar}. |
|
|
2157 |
|
|
2158 @item stop |
|
|
2159 @samp{-S} in Make. |
|
|
2160 |
|
|
2161 @item strict |
|
|
2162 @samp{-s} in @code{recode}. |
|
|
2163 |
|
|
2164 @item strip |
|
|
2165 @samp{-s} in @code{install}. |
|
|
2166 |
|
|
2167 @item strip-all |
|
|
2168 @samp{-s} in @code{strip}. |
|
|
2169 |
|
|
2170 @item strip-debug |
|
|
2171 @samp{-S} in @code{strip}. |
|
|
2172 |
|
|
2173 @item submitter |
|
|
2174 @samp{-s} in @code{shar}. |
|
|
2175 |
|
|
2176 @item suffix |
|
|
2177 @samp{-S} in @code{cp}, @code{ln}, @code{mv}. |
|
|
2178 |
|
|
2179 @item suffix-format |
|
|
2180 @samp{-b} in @code{csplit}. |
|
|
2181 |
|
|
2182 @item sum |
|
|
2183 @samp{-s} in @code{gprof}. |
|
|
2184 |
|
|
2185 @item summarize |
|
|
2186 @samp{-s} in @code{du}. |
|
|
2187 |
|
|
2188 @item symbolic |
|
|
2189 @samp{-s} in @code{ln}. |
|
|
2190 |
|
|
2191 @item symbols |
|
|
2192 Used in GDB and @code{objdump}. |
|
|
2193 |
|
|
2194 @item synclines |
|
|
2195 @samp{-s} in @code{m4}. |
|
|
2196 |
|
|
2197 @item sysname |
|
|
2198 @samp{-s} in @code{uname}. |
|
|
2199 |
|
|
2200 @item tabs |
|
|
2201 @samp{-t} in @code{expand} and @code{unexpand}. |
|
|
2202 |
|
|
2203 @item tabsize |
|
|
2204 @samp{-T} in @code{ls}. |
|
|
2205 |
|
|
2206 @item terminal |
|
|
2207 @samp{-T} in @code{tput} and @code{ul}. |
|
|
2208 @samp{-t} in @code{wdiff}. |
|
|
2209 |
|
|
2210 @item text |
|
|
2211 @samp{-a} in @code{diff}. |
|
|
2212 |
|
|
2213 @item text-files |
|
|
2214 @samp{-T} in @code{shar}. |
|
|
2215 |
|
|
2216 @item time |
|
|
2217 Used in @code{ls} and @code{touch}. |
|
|
2218 |
|
|
2219 @item to-stdout |
|
|
2220 @samp{-O} in @code{tar}. |
|
|
2221 |
|
|
2222 @item total |
|
|
2223 @samp{-c} in @code{du}. |
|
|
2224 |
|
|
2225 @item touch |
|
|
2226 @samp{-t} in Make, @code{ranlib}, and @code{recode}. |
|
|
2227 |
|
|
2228 @item trace |
|
|
2229 @samp{-t} in @code{m4}. |
|
|
2230 |
|
|
2231 @item traditional |
|
|
2232 @samp{-t} in @code{hello}; |
|
|
2233 @samp{-G} in @code{m4} and @code{ptx}. |
|
|
2234 |
|
|
2235 @item tty |
|
|
2236 Used in GDB. |
|
|
2237 |
|
|
2238 @item typedefs |
|
|
2239 @samp{-t} in @code{ctags}. |
|
|
2240 |
|
|
2241 @item typedefs-and-c++ |
|
|
2242 @samp{-T} in @code{ctags}. |
|
|
2243 |
|
|
2244 @item typeset-mode |
|
|
2245 @samp{-t} in @code{ptx}. |
|
|
2246 |
|
|
2247 @item uncompress |
|
|
2248 @samp{-z} in @code{tar}. |
|
|
2249 |
|
|
2250 @item unconditional |
|
|
2251 @samp{-u} in @code{cpio}. |
|
|
2252 |
|
|
2253 @item undefine |
|
|
2254 @samp{-U} in @code{m4}. |
|
|
2255 |
|
|
2256 @item undefined-only |
|
|
2257 @samp{-u} in @code{nm}. |
|
|
2258 |
|
|
2259 @item update |
|
|
2260 @samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. |
|
|
2261 |
|
|
2262 @item uuencode |
|
|
2263 @samp{-B} in @code{shar}. |
|
|
2264 |
|
|
2265 @item vanilla-operation |
|
|
2266 @samp{-V} in @code{shar}. |
|
|
2267 |
|
|
2268 @item verbose |
|
|
2269 Print more information about progress. Many programs support this. |
|
|
2270 |
|
|
2271 @item verify |
|
|
2272 @samp{-W} in @code{tar}. |
|
|
2273 |
|
|
2274 @item version |
|
|
2275 Print the version number. |
|
|
2276 |
|
|
2277 @item version-control |
|
|
2278 @samp{-V} in @code{cp}, @code{ln}, @code{mv}. |
|
|
2279 |
|
|
2280 @item vgrind |
|
|
2281 @samp{-v} in @code{ctags}. |
|
|
2282 |
|
|
2283 @item volume |
|
|
2284 @samp{-V} in @code{tar}. |
|
|
2285 |
|
|
2286 @item what-if |
|
|
2287 @samp{-W} in Make. |
|
|
2288 |
|
|
2289 @item whole-size-limit |
|
|
2290 @samp{-l} in @code{shar}. |
|
|
2291 |
|
|
2292 @item width |
|
|
2293 @samp{-w} in @code{ls} and @code{ptx}. |
|
|
2294 |
|
|
2295 @item word-regexp |
|
|
2296 @samp{-W} in @code{ptx}. |
|
|
2297 |
|
|
2298 @item writable |
|
|
2299 @samp{-T} in @code{who}. |
|
|
2300 |
|
|
2301 @item zeros |
|
|
2302 @samp{-z} in @code{gprof}. |
|
|
2303 |
|
|
2304 @end table |
|
|
2305 |
|
|
2306 @node Documentation |
|
|
2307 @chapter Documenting Programs |
|
|
2308 |
|
|
2309 Please use Texinfo for documenting GNU programs. See the Texinfo |
|
|
2310 manual, either the hardcopy or the version in the GNU Emacs Info |
|
|
2311 subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g., those |
|
|
2312 under the @file{man/} directory in the GNU Emacs distribution) for |
|
|
2313 examples. |
|
|
2314 |
|
|
2315 The title page of the manual should state the version of the program |
|
|
2316 which the manual applies to. The Top node of the manual should also |
|
|
2317 contain this information. If the manual is changing more frequently |
|
|
2318 than or independent of the program, also state a version number for |
|
|
2319 the manual in both of these places. |
|
|
2320 |
|
|
2321 The manual should document all command-line arguments and all |
|
|
2322 commands. It should give examples of their use. But don't organize |
|
|
2323 the manual as a list of features. Instead, organize it by the |
|
|
2324 concepts a user will have before reaching that point in the manual. |
|
|
2325 Address the goals that a user will have in mind, and explain how to |
|
|
2326 accomplish them. Don't use Unix man pages as a model for how to |
|
|
2327 write GNU documentation; they are a bad example to follow. |
|
|
2328 |
|
|
2329 The manual should have a node named @samp{@var{program} Invocation} or |
|
|
2330 @samp{Invoking @var{program}}, where @var{program} stands for the name |
|
|
2331 of the program being described, as you would type it in the shell to run |
|
|
2332 the program. This node (together with its subnodes, if any) should |
|
|
2333 describe the program's command line arguments and how to run it (the |
|
|
2334 sort of information people would look in a man page for). Start with an |
|
|
2335 @samp{@@example} containing a template for all the options and arguments |
|
|
2336 that the program uses. |
|
|
2337 |
|
|
2338 Alternatively, put a menu item in some menu whose item name fits one of |
|
|
2339 the above patterns. This identifies the node which that item points to |
|
|
2340 as the node for this purpose, regardless of the node's actual name. |
|
|
2341 |
|
|
2342 There will be automatic features for specifying a program name and |
|
|
2343 quickly reading just this part of its manual. |
|
|
2344 |
|
|
2345 If one manual describes several programs, it should have such a node for |
|
|
2346 each program described. |
|
|
2347 |
|
|
2348 In addition to its manual, the package should have a file named |
|
|
2349 @file{NEWS} which contains a list of user-visible changes worth |
|
|
2350 mentioning. In each new release, add items to the front of the file and |
|
|
2351 identify the version they pertain to. Don't discard old items; leave |
|
|
2352 them in the file after the newer items. This way, a user upgrading from |
|
|
2353 any previous version can see what is new. |
|
|
2354 |
|
|
2355 If the @file{NEWS} file gets very long, move some of the older items |
|
|
2356 into a file named @file{ONEWS} and put a note at the end referring the |
|
|
2357 user to that file. |
|
|
2358 |
|
|
2359 Please do not use the term ``pathname'' that is used in Unix |
|
|
2360 documentation; use ``file name'' (two words) instead. We use the term |
|
|
2361 ``path'' only for search paths, which are lists of file names. |
|
|
2362 |
|
|
2363 It is ok to supply a man page for the program as well as a Texinfo |
|
|
2364 manual if you wish to. But keep in mind that supporting a man page |
|
|
2365 requires continual effort, each time the program is changed. Any time |
|
|
2366 you spend on the man page is time taken away from more useful things you |
|
|
2367 could contribute. |
|
|
2368 |
|
|
2369 Thus, even if a user volunteers to donate a man page, you may find this |
|
|
2370 gift costly to accept. Unless you have time on your hands, it may be |
|
|
2371 better to refuse the man page unless the same volunteer agrees to take |
|
|
2372 full responsibility for maintaining it---so that you can wash your hands |
|
|
2373 of it entirely. If the volunteer ceases to do the job, then don't feel |
|
|
2374 obliged to pick it up yourself; it may be better to withdraw the man |
|
|
2375 page until another volunteer offers to carry on with it. |
|
|
2376 |
|
|
2377 Alternatively, if you expect the discrepancies to be small enough that |
|
|
2378 the man page remains useful, put a prominent note near the beginning of |
|
|
2379 the man page explaining that you don't maintain it and that the Texinfo |
|
|
2380 manual is more authoritative, and describing how to access the Texinfo |
|
|
2381 documentation. |
|
|
2382 |
|
|
2383 @node Releases |
|
|
2384 @chapter Making Releases |
|
|
2385 |
|
|
2386 Package the distribution of Foo version 69.96 in a gzipped tar file |
|
|
2387 named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory |
|
|
2388 named @file{foo-69.96}. |
|
|
2389 |
|
|
2390 Building and installing the program should never modify any of the files |
|
|
2391 contained in the distribution. This means that all the files that form |
|
|
2392 part of the program in any way must be classified into @dfn{source |
|
|
2393 files} and @dfn{non-source files}. Source files are written by humans |
|
|
2394 and never changed automatically; non-source files are produced from |
|
|
2395 source files by programs under the control of the Makefile. |
|
|
2396 |
|
|
2397 Naturally, all the source files must be in the distribution. It is okay |
|
|
2398 to include non-source files in the distribution, provided they are |
|
|
2399 up-to-date and machine-independent, so that building the distribution |
|
|
2400 normally will never modify them. We commonly include non-source files |
|
|
2401 produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid |
|
|
2402 unnecessary dependencies between our distributions, so that users can |
|
|
2403 install whichever packages they want to install. |
|
|
2404 |
|
|
2405 Non-source files that might actually be modified by building and |
|
|
2406 installing the program should @strong{never} be included in the |
|
|
2407 distribution. So if you do distribute non-source files, always make |
|
|
2408 sure they are up to date when you make a new distribution. |
|
|
2409 |
|
|
2410 Make sure that the directory into which the distribution unpacks (as |
|
|
2411 well as any subdirectories) are all world-writable (octal mode 777). |
|
|
2412 This is so that old versions of @code{tar} which preserve the |
|
|
2413 ownership and permissions of the files from the tar archive will be |
|
|
2414 able to extract all the files even if the user is unprivileged. |
|
|
2415 |
|
|
2416 Make sure that all the files in the distribution are world-readable. |
|
|
2417 |
|
|
2418 Make sure that no file name in the distribution is more than 14 |
|
|
2419 characters long. Likewise, no file created by building the program |
|
|
2420 should have a name longer than 14 characters. The reason for this is |
|
|
2421 that some systems adhere to a foolish interpretation of the POSIX |
|
|
2422 standard, and refuse to open a longer name, rather than truncating as |
|
|
2423 they did in the past. |
|
|
2424 |
|
|
2425 Don't include any symbolic links in the distribution itself. If the tar |
|
|
2426 file contains symbolic links, then people cannot even unpack it on |
|
|
2427 systems that don't support symbolic links. Also, don't use multiple |
|
|
2428 names for one file in different directories, because certain file |
|
|
2429 systems cannot handle this and that prevents unpacking the |
|
|
2430 distribution. |
|
|
2431 |
|
|
2432 Try to make sure that all the file names will be unique on MS-DOG. A |
|
|
2433 name on MS-DOG consists of up to 8 characters, optionally followed by a |
|
|
2434 period and up to three characters. MS-DOG will truncate extra |
|
|
2435 characters both before and after the period. Thus, |
|
|
2436 @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they |
|
|
2437 are truncated to @file{foobarha.c} and @file{foobarha.o}, which are |
|
|
2438 distinct. |
|
|
2439 |
|
|
2440 Include in your distribution a copy of the @file{texinfo.tex} you used |
|
|
2441 to test print any @file{*.texinfo} files. |
|
|
2442 |
|
|
2443 Likewise, if your program uses small GNU software packages like regex, |
|
|
2444 getopt, obstack, or termcap, include them in the distribution file. |
|
|
2445 Leaving them out would make the distribution file a little smaller at |
|
|
2446 the expense of possible inconvenience to a user who doesn't know what |
|
|
2447 other files to get. |
|
|
2448 |
|
|
2449 @contents |
|
|
2450 |
|
|
2451 @bye |
