gnu coding standards

7/28/2019 GNU Coding Standards

1/84

GNU Coding Standards

Richard Stallman, et al.last updated April 27, 2013


2/84

The GNU coding standards, last updated April 27, 2013.Copyright c 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Sotware Foundation, Inc.

Permission is granted to copy, distribute and/or modiy this document under the terms othe GNU Free Documentation License, Version 1.3 or any later version published by theFree Sotware Foundation; with no Invariant Sections, with no Front-Cover Texts, and withno Back-Cover Texts. A copy o the license is included in the section entitled GNU FreeDocumentation License.


3/84

i

Table o Contents

1 About the GNU Coding Standards . . . . . . . . . . . 1

2 Keeping Free Sotware Free . . . . . . . . . . . . . . . . . . . . 1

2.1 Reerring to Proprietary Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.2 Accepting Contributions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.3 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 General Program Design . . . . . . . . . . . . . . . . . . . . . . . 3

3.1 Which Languages to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33.2 Compatibility with Other Implementations . . . . . . . . . . . . . . . . . . . . . 43.3 Using Non-standard Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.4 Standard C and Pre-Standard C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

53.5 Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Program Behavior or All Programs . . . . . . . . . . 7

4.1 Non-GNU Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 Writing Robust Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.3 Library Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.4 Formatting Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.5 Standards or Interaces Generally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.6 Standards or Graphical Interaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.7 Standards or Command Line Interaces . . . . . . . . . . . . . . . . . . . . . . . 11

4.7.1 --version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

114.7.2 --help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.8 Standards or Dynamic Plug-in Interaces. . . . . . . . . . . . . . . . . . . . . . 144.9 Table o Long Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.10 OID Allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.11 Memory Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314.12 File Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5 Making The Best Use o C . . . . . . . . . . . . . . . . . . . 31

5.1 Formatting Your Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.2 Commenting Your Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345.3 Clean Use o C Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.4 Naming Variables, Functions, and Files

. . . . . . . . . . . . . . . . . . . . . . . .37

5.5 Portability between System Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385.6 Portability between CPUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385.7 Calling System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395.8 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405.9 Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415.10 Quote Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425.11 Mmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42


4/84

ii

6 Documenting Programs . . . . . . . . . . . . . . . . . . . . . . . 42

6.1 GNU Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436.2 Doc Strings and Manuals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446.3 Manual Structure Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456.4 License or Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

6.5 Manual Credits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

456.6 Printed Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456.7 The NEWS File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.8 Change Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6.8.1 Change Log Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.8.2 Style o Change Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476.8.3 Simple Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486.8.4 Conditional Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486.8.5 Indicating the Part Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

6.9 Man Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496.10 Reading other Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

7 The Release Process. . . . . . . . . . . . . . . . . . . . . . . . . .

507.1 How Conguration Should Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.2 Makele Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

7.2.1 General Conventions or Makeles . . . . . . . . . . . . . . . . . . . . . . . . 537.2.2 Utilities in Makeles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547.2.3 Variables or Speciying Commands . . . . . . . . . . . . . . . . . . . . . . . 557.2.4 DESTDIR: Support or Staged Installs . . . . . . . . . . . . . . . . . . . . . 567.2.5 Variables or Installation Directories . . . . . . . . . . . . . . . . . . . . . . 577.2.6 Standard Targets or Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617.2.7 Install Command Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

7.3 Making Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8 Reerences to Non-Free Sotware andDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Appendix A GNU Free Documentation License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78


5/84

Chapter 2: Keeping Free Sotware Free 1

1 About the GNU Coding Standards

The GNU Coding Standards were written by Richard Stallman and other GNU Project

volunteers. Their purpose is to make the GNU system clean, consistent, and easy to install.This document can also be read as a guide to writing portable, robust and reliable programs.It ocuses on programs written in C, but many o the rules and principles are useul even iyou write in another programming language. The rules oten state reasons or writing in acertain way.

I you did not obtain this le directly rom the GNU project and recently, please checkor a newer version. You can get the GNU Coding Standards rom the GNU web server inmany diferent ormats, including the Texino source, PDF, HTML, DVI, plain text, andmore, at: http://www.gnu.org/prep/standards/.

I you are maintaining an ocial GNU package, in addition to this document, please

read and ollow the GNU maintainer inormation (see Section Contents in Inormationor Maintainers o GNU Sotware).

I you want to receive difs or every change to these GNU documents, join the mailinglist [email protected], via the web interace at http://lists.gnu.org/

mailman/listinfo/gnustandards-commit. Archives are also available there.

Please send corrections or suggestions or this document to [email protected]. Iyou make a suggestion, please include a suggested new wording or it, to help us consider thesuggestion eciently. We preer a context dif to the Texino source, but i thats dicultor you, you can make a context dif or some other version o this document, or propose itin any way that makes it clear. The source repository or this document can be ound athttp://savannah.gnu.org/projects/gnustandards .

These standards cover the minimum o what is important when writing a GNU package.Likely, the need or additional standards will come up. Sometimes, you might suggest thatsuch standards be added to this document. I you think your standards would be generallyuseul, please do suggest them.

You should also set standards or your package on many questions not addressed or notrmly specied here. The most important point is to be sel-consistenttry to stick tothe conventions you pick, and try to document them as much as possible. That way, yourprogram will be more maintainable by others.

The GNU Hello program serves as an example o how to ollow the GNU coding standardsor a trivial program. http://www.gnu.org/software/hello/hello.html .

This release o the GNU Coding Standards was last updated April 27, 2013.

2 Keeping Free Sotware Free

This chapter discusses how you can make sure that GNU sotware avoids legal diculties,and other related issues.
http://www.gnu.org/prep/standards/http://maintain.pdf/http://maintain.pdf/http://maintain.pdf/http://lists.gnu.org/mailman/listinfo/gnustandards-commithttp://lists.gnu.org/mailman/listinfo/gnustandards-commitmailto:[email protected]://savannah.gnu.org/projects/gnustandardshttp://www.gnu.org/software/hello/hello.htmlhttp://www.gnu.org/software/hello/hello.htmlhttp://savannah.gnu.org/projects/gnustandardsmailto:[email protected]://lists.gnu.org/mailman/listinfo/gnustandards-commithttp://lists.gnu.org/mailman/listinfo/gnustandards-commithttp://maintain.pdf/http://maintain.pdf/http://www.gnu.org/prep/standards/


6/84

Chapter 2: Keeping Free Sotware Free 2

2.1 Reerring to Proprietary Programs

Dont in any circumstances reer to Unix source code or or during your work on GNU! (Orto any other proprietary programs.)

I you have a vague recollection o the internals o a Unix program, this does not abso-lutely mean you cant write an imitation o it, but do try to organize the imitation internallyalong diferent lines, because this is likely to make the details o the Unix version irrelevantand dissimilar to your results.

For example, Unix utilities were generally optimized to minimize memory use; i you goor speed instead, your program will be very diferent. You could keep the entire input lein memory and scan it there instead o using stdio. Use a smarter algorithm discoveredmore recently than the Unix program. Eliminate use o temporary les. Do it in one passinstead o two (we did this in the assembler).

Or, on the contrary, emphasize simplicity instead o speed. For some applications, thespeed o todays computers makes simpler algorithms adequate.

Or go or generality. For example, Unix programs oten have static tables or xed-sizestrings, which make or arbitrary limits; use dynamic allocation instead. Make sure yourprogram handles NULs and other unny characters in the input les. Add a programminglanguage or extensibility and write part o the program in that language.

Or turn some parts o the program into independently usable libraries. Or use a simplegarbage collector instead o tracking precisely when to ree memory, or use a new GNUacility such as obstacks.

2.2 Accepting Contributions

I the program you are working on is copyrighted by the Free Sotware Foundation, thenwhen someone else sends you a piece o code to add to the program, we need legal papers

to use itjust as we asked you to sign papers initially. Each person who makes a nontrivialcontribution to a program must sign some sort o legal papers in order or us to have cleartitle to the program; the main author alone is not enough.

So, beore adding in any contributions rom other people, please tell us, so we can arrangeto get the papers. Then wait until we tell you that we have received the signed papers,beore you actually use the contribution.

This applies both beore you release the program and aterward. I you receive difs tox a bug, and they make signicant changes, we need legal papers or that change.

This also applies to comments and documentation les. For copyright law, commentsand code are just text. Copyright applies to all kinds o text, so we need legal papers orall kinds.

We know it is rustrating to ask or legal papers; its rustrating or us as well. But i youdont wait, you are going out on a limbor example, what i the contributors employerwont sign a disclaimer? You might have to take that code out again!

You dont need papers or changes o a ew lines here or there, since they are notsignicant or copyright purposes. Also, you dont need papers i all you get rom thesuggestion is some ideas, not actual code which you use. For example, i someone sent youone implementation, but you write a diferent implementation o the same idea, you dontneed to get papers.


7/84

Chapter 3: General Program Design 3

The very worst thing is i you orget to tell us about the other contributor. We could bevery embarrassed in court some day as a result.

We have more detailed advice or maintainers o GNU packages. I you have reached

the stage o maintaining a GNU program (whether released or not), please take a look: seeSection Legal Matters in Inormation or GNU Maintainers.

2.3 Trademarks

Please do not include any trademark acknowledgements in GNU sotware packages or doc-umentation.

Trademark acknowledgements are the statements that such-and-such is a trademark oso-and-so. The GNU Project has no objection to the basic idea o trademarks, but theseacknowledgements eel like kowtowing, and there is no legal requirement or them, so wedont use them.

What is legally required, as regards other peoples trademarks, is to avoid using them in

ways which a reader might reasonably understand as naming or labeling our own programsor activities. For example, since Objective C is (or at least was) a trademark, we madesure to say that we provide a compiler or the Objective C language rather than anObjective C compiler. The latter would have been meant as a shorter way o saying theormer, but it does not explicitly state the relationship, so it could be misinterpreted asusing Objective C as a label or the compiler rather than or the language.

Please dont use win as an abbreviation or Microsot Windows in GNU sotware ordocumentation. In hacker terminology, calling something a win is a orm o praise. I youwish to praise Microsot Windows when speaking on your own, by all means do so, but notin GNU sotware. Usually we write the name Windows in ull, but when brevity is veryimportant (as in le names and sometimes symbol names), we abbreviate it to w. For

instance, the les and unctions in Emacs that deal with Windows start with w32.

3 General Program Design

This chapter discusses some o the issues you should take into account when designing yourprogram.

3.1 Which Languages to Use

When you want to use a language that gets compiled and runs at high speed, the bestlanguage to use is C. Using another language is like using a non-standard eature: it will

cause trouble or users. Even i GCC supports the other language, users may nd it in-convenient to have to install the compiler or that other language in order to build yourprogram. For example, i you write your program in C++, people will have to install theGNU C++ compiler in order to compile your program.

C has one other advantage over C++ and other compiled languages: more people knowC, so more people will nd it easy to read and modiy the program i it is written in C.

So in general it is much better to use C, rather than the comparable alternatives.

But there are two exceptions to that conclusion:
http://maintain.pdf/http://maintain.pdf/http://maintain.pdf/


8/84


It is no problem to use another language to write a tool specically intended or usewith that language. That is because the only people who want to build the tool willbe those who have installed the other language anyway.

I an application is o interest only to a narrow part o the community, then the questiono which language it is written in has less efect on other people, so you may as wellplease yoursel.

Many programs are designed to be extensible: they include an interpreter or a languagethat is higher level than C. Oten much o the program is written in that language, too.The Emacs editor pioneered this technique.

The standard extensibility interpreter or GNU sotware is Guile (http://www.gnu.org/software/guile/), which implements the language Scheme (an especially clean and simpledialect o Lisp). Guile also includes bindings or GTK+/GNOME, making it practical towrite modern GUI unctionality within Guile. We dont reject programs written in otherscripting languages such as Perl and Python, but using Guile is very important or theoverall consistency o the GNU system.

3.2 Compatibility with Other Implementations

With occasional exceptions, utility programs and libraries or GNU should be upward com-patible with those in Berkeley Unix, and upward compatible with Standard C i StandardC species their behavior, and upward compatible with POSIX i POSIX species theirbehavior.

When these standards conict, it is useul to ofer compatibility modes or each o them.

Standard C and POSIX prohibit many kinds o extensions. Feel ree to make the exten-sions anyway, and include a --ansi, --posix, or --compatible option to turn themof. However, i the extension has a signicant chance o breaking any real programs or

scripts, then it is not really upward compatible. So you should try to redesign its interaceto make it upward compatible.

Many GNU programs suppress extensions that conict with POSIX i the environmentvariable POSIXLY_CORRECT is dened (even i it is dened with a null value). Please makeyour program recognize this variable i appropriate.

When a eature is used only by users (not by programs or command les), and it is donepoorly in Unix, eel ree to replace it completely with something totally diferent and better.(For example, vi is replaced with Emacs.) But it is nice to ofer a compatible eature aswell. (There is a ree vi clone, so we ofer it.)

Additional useul eatures are welcome regardless o whether there is any precedent orthem.

3.3 Using Non-standard Features

Many GNU acilities that already exist support a number o convenient extensions over thecomparable Unix acilities. Whether to use these extensions in implementing your programis a dicult question.

On the one hand, using the extensions can make a cleaner program. On the other hand,people will not be able to build the program unless the other GNU tools are available. Thismight cause the program to work on ewer kinds o machines.
http://www.gnu.org/software/guile/http://www.gnu.org/software/guile/http://www.gnu.org/software/guile/http://www.gnu.org/software/guile/


9/84


With some extensions, it might be easy to provide both alternatives. For example, youcan dene unctions with a keyword INLINE and dene that as a macro to expand intoeither inline or nothing, depending on the compiler.

In general, perhaps it is best not to use the extensions i you can straightorwardly dowithout them, but to use the extensions i they are a big improvement.

An exception to this rule are the large, established programs (such as Emacs) which runon a great variety o systems. Using GNU extensions in such programs would make manyusers unhappy, so we dont do that.

Another exception is or programs that are used as part o compilation: anything thatmust be compiled with other compilers in order to bootstrap the GNU compilation acilities.I these require the GNU compiler, then no one can compile them without having theminstalled already. That would be extremely troublesome in certain cases.

3.4 Standard C and Pre-Standard C

1989 Standard C is widespread enough now that it is ok to use its eatures in programs.There is one exception: do not ever use the trigraph eature o Standard C.

The 1999 and 2011 editions o Standard C are not ully supported on all platorms. Iyou aim to support compilation by compilers other than GCC, you should not require theseC eatures in your programs. It is ok to use these eatures conditionally when the compilersupports them.

I your program is only meant to compile with GCC, then you can use these eatures iGCC supports them, when they give substantial benet.

However, it is easy to support pre-standard compilers in most programs, so i you knowhow to do that, eel ree.

To support pre-standard C, instead o writing unction denitions in standard prototype

orm,

int

foo (int x, int y)

...

write the denition in pre-standard style like this,

int

foo (x, y)

int x, y;

...

and use a separate declaration to speciy the argument prototype:

int foo (int, int);You need such a declaration anyway, in a header le, to get the benet o prototypes in

all the les where the unction is called. And once you have the declaration, you normallylose nothing by writing the unction denition in the pre-standard style.

This technique does not work or integer types narrower than int. I you think o anargument as being o a type narrower than int, declare it as int instead.

There are a ew special cases where this technique is hard to use. For example, i aunction argument needs to hold the system type dev_t, you run into trouble, because


10/84


dev_t is shorter than int on some machines; but you cannot use int instead, becausedev_t is wider than int on some machines. There is no type you can saely use on allmachines in a non-standard denition. The only way to support non-standard C and passsuch an argument is to check the width o dev_t using Autocon and choose the argumenttype accordingly. This may not be worth the trouble.

In order to support pre-standard compilers that do not recognize prototypes, you maywant to use a preprocessor macro like this:

/* Declare the prototype for a general external function. */

#if defined (__STDC__) || defined (WINDOWSNT)

#define P_(proto) proto

#else

#define P_(proto) ()

#endif

3.5 Conditional Compilation

When supporting conguration options already known when building your program wepreer using if (... ) over conditional compilation, as in the ormer case the compiler isable to perorm more extensive checking o all possible code paths.

For example, please write

if (HAS_FOO)...

else...

instead o:

#ifdef HAS_FOO...

#else...

#endif

A modern compiler such as GCC will generate exactly the same code in both cases, andwe have been using similar techniques with good success in several projects. O course, theormer method assumes that HAS_FOO is dened as either 0 or 1.

While this is not a silver bullet solving all portability problems, and is not always appro-priate, ollowing this policy would have saved GCC developers many hours, or even days,per year.

In the case o unction-like macros like REVERSIBLE_CC_MODE in GCC which cannot besimply used in if (...) statements, there is an easy workaround. Simply introduce anothermacro HAS_REVERSIBLE_CC_MODE as in the ollowing example:

#ifdef REVERSIBLE_CC_MODE#define HAS_REVERSIBLE_CC_MODE 1#else#define HAS_REVERSIBLE_CC_MODE 0#endif


11/84

Chapter 4: Program Behavior or All Programs 7

4 Program Behavior or All Programs

This chapter describes conventions or writing robust sotware. It also describes general

standards or error messages, the command line interace, and how libraries should behave.

4.1 Non-GNU Standards

The GNU Project regards standards published by other organizations as suggestions, notorders. We consider those standards, but we do not obey them. In developing a GNUprogram, you should implement an outside standards specications when that makes theGNU system better overall in an objective sense. When it doesnt, you shouldnt.

In most cases, ollowing published standards is convenient or usersit means that theirprograms or scripts will work more portably. For instance, GCC implements nearly allthe eatures o Standard C as specied by that standard. C program developers would beunhappy i it did not. And GNU utilities mostly ollow specications o POSIX.2; shell

script writers and users would be unhappy i our programs were incompatible.But we do not ollow either o these specications rigidly, and there are specic points

on which we decided not to ollow them, so as to make the GNU system better or users.

For instance, Standard C says that nearly all extensions to C are prohibited. How silly!GCC implements many extensions, some o which were later adopted as part o the standard.I you want these constructs to give an error message as required by the standard, youmust speciy --pedantic, which was implemented only so that we can say GCC is a100% implementation o the standard, not because there is any reason to actually use it.

POSIX.2 species that df and du must output sizes by deault in units o 512 bytes.What users want is units o 1k, so that is what we do by deault. I you want the ridiculousbehavior required by POSIX, you must set the environment variable POSIXLY_CORRECT

(which was originally going to be named POSIX_ME_HARDER).

GNU utilities also depart rom the letter o the POSIX.2 specication when they supportlong-named command-line options, and intermixing options with ordinary arguments. Thisminor incompatibility with POSIX is never a problem in practice, and it is very useul.

In particular, dont reject a new eature, or remove an old one, merely because a standardsays it is orbidden or deprecated.

4.2 Writing Robust Programs

Avoid arbitrary limits on the length or number o any data structure, including le names,lines, les, and symbols, by allocating all data structures dynamically. In most Unix utilities,

long lines are silently truncated. This is not acceptable in a GNU utility.Utilities reading les should not drop NUL characters, or any other nonprinting charac-

ters including those with codes above 0177. The only sensible exceptions would be utilitiesspecically intended or interace to certain types o terminals or printers that cant handlethose characters. Whenever possible, try to make programs work properly with sequenceso bytes that represent multibyte characters; UTF-8 is the most important.

Check every system call or an error return, unless you know you wish to ignore errors.Include the system error text (rom perror, strerror, or equivalent) in every error message


12/84


resulting rom a ailing system call, as well as the name o the le i any and the name othe utility. Just cannot open oo.c or stat ailed is not sucient.

Check every call to malloc or realloc to see i it returned zero. Check realloc even

i you are making the block smaller; in a system that rounds block sizes to a power o 2,realloc may get a diferent block i you ask or less space.

In Unix, realloc can destroy the storage block i it returns zero. GNU realloc doesnot have this bug: i it ails, the original block is unchanged. Feel ree to assume the bugis xed. I you wish to run your program on Unix, and wish to avoid lossage in this case,you can use the GNU malloc.

You must expect free to alter the contents o the block that was reed. Anything youwant to etch rom the block, you must etch beore calling free.

I malloc ails in a noninteractive program, make that a atal error. In an interactiveprogram (one that reads commands rom the user), it is better to abort the command andreturn to the command reader loop. This allows the user to kill other processes to ree up

virtual memory, and then try the command again.Use getopt_long to decode arguments, unless the argument syntax makes this unrea-

sonable.

When static storage is to be written in during program execution, use explicit C codeto initialize it. Reserve C initialized declarations or data that will not be changed.

Try to avoid low-level interaces to obscure Unix data structures (such as le directories,utmp, or the layout o kernel memory), since these are less likely to work compatibly. Iyou need to nd all the les in a directory, use readdir or some other high-level interace.These are supported compatibly by GNU.

The preerred signal handling acilities are the BSD variant o signal, and the POSIXsigaction unction; the alternative USG signal interace is an inerior design.

Nowadays, using the POSIX signal unctions may be the easiest way to make a programportable. I you use signal, then on GNU/Linux systems running GNU libc version 1, youshould include bsd/signal.h instead o signal.h, so as to get BSD behavior. It is up toyou whether to support systems where signal has only the USG behavior, or give up onthem.

In error checks that detect impossible conditions, just abort. There is usually no pointin printing any message. These checks indicate the existence o bugs. Whoever wants to xthe bugs will have to read the source code and run a debugger. So explain the problem withcomments in the source. The relevant data will be in variables, which are easy to examinewith the debugger, so there is no point moving them elsewhere.

Do not use a count o errors as the exit status or a program. That does not work, because

exit status values are limited to 8 bits (0 through 255). A single run o the program mighthave 256 errors; i you try to return 256 as the exit status, the parent process will see 0 asthe status, and it will appear that the program succeeded.

I you make temporary les, check the TMPDIR environment variable; i that variable isdened, use the specied directory instead o /tmp.

In addition, be aware that there is a possible security problem when creating temporaryles in world-writable directories. In C, you can avoid this problem by creating temporaryles in this manner:


13/84


fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);

or by using the mkstemps unction rom Gnulib (see Section mkstemps in Gnulib).

In bash, use set -C (long name noclobber) to avoid this problem. In addition, the

mktemp utility is a more general solution or creating temporary les rom shell scripts (seeSection mktemp invocation in GNU Coreutils).

4.3 Library Behavior

Try to make library unctions reentrant. I they need to do dynamic storage allocation, atleast try to avoid any nonreentrancy aside rom that o malloc itsel.

Here are certain name conventions or libraries, to avoid name conicts.

Choose a name prex or the library, more than two characters long. All external unctionand variable names should start with this prex. In addition, there should only be one othese in any given library member. This usually means putting each one in a separatesource le.

An exception can be made when two external symbols are always used together, so thatno reasonable program could use one without the other; then they can both go in the samele.

External symbols that are not documented entry points or the user should have namesbeginning with _. The _ should be ollowed by the chosen name prex or the library, toprevent collisions with other libraries. These can go in the same les with user entry pointsi you like.

Static unctions and variables can be used as you like and need not t any namingconvention.

4.4 Formatting Error Messages

Error messages rom compilers should look like this:

sourcefile:lineno: message

I you want to mention the column number, use one o these ormats:

sourcefile:lineno:column: message

sourcefile:lineno.column: message

Line numbers should start rom 1 at the beginning o the le, and column numbers shouldstart rom 1 at the beginning o the line. (Both o these conventions are chosen or compat-ibility.) Calculate column numbers assuming that space and all ASCII printing charactershave equal width, and assuming tab stops every 8 columns. For non-ASCII characters,

Unicode character widths should be used when in a UTF-8 locale; GNU libc and GNUgnulib provide suitable wcwidth unctions.

The error message can also give both the starting and ending positions o the erroneoustext. There are several ormats so that you can avoid redundant inormation such as aduplicate line number. Here are the possible ormats:

sourcefile:line1.column1-line2.column2: message

sourcefile:line1.column1-column2: message

sourcefile:line1-line2: message
http://gnulib.pdf/http://gnulib.pdf/http://coreutils.pdf/http://coreutils.pdf/http://coreutils.pdf/http://gnulib.pdf/


14/84


When an error is spread over several les, you can use this ormat:

file1:line1.column1-file2:line2.column2: message

Error messages rom other noninteractive programs should look like this:

program:sourcefile:lineno: message

when there is an appropriate source le, or like this:

program: message

when there is no relevant source le.

I you want to mention the column number, use this ormat:

program:sourcefile:lineno:column: message

In an interactive program (one that is reading commands rom a terminal), it is betternot to include the program name in an error message. The place to indicate which programis running is in the prompt or with the screen layout. (When the same program runs withinput rom a source other than a terminal, it is not interactive and would do best to printerror messages using the noninteractive style.)

The string message should not begin with a capital letter when it ollows a program nameand/or le name, because that isnt the beginning o a sentence. (The sentence conceptuallystarts at the beginning o the line.) Also, it should not end with a period.

Error messages rom interactive programs, and other messages such as usage messages,should start with a capital letter. But they should not end with a period.

4.5 Standards or Interaces Generally

Please dont make the behavior o a utility depend on the name used to invoke it. It isuseul sometimes to make a link to a utility with a diferent name, and that should notchange what it does.

Instead, use a run time option or a compilation switch or both to select among thealternate behaviors.

Likewise, please dont make the behavior o the program depend on the type o outputdevice it is used with. Device independence is an important principle o the systemsdesign; do not compromise it merely to save someone rom typing an option now and then.(Variation in error message syntax when using a terminal is ok, because that is a side issuethat people do not depend on.)

I you think one behavior is most useul when the output is to a terminal, and another

is most useul when the output is a le or a pipe, then it is usually best to make the deaultbehavior the one that is useul with output to a terminal, and have an option or the otherbehavior.

Compatibility requires certain programs to depend on the type o output device. Itwould be disastrous i ls or sh did not do so in the way all users expect. In some o thesecases, we supplement the program with a preerred alternate version that does not dependon the output device type. For example, we provide a dir program much like ls exceptthat its deault output ormat is always multi-column ormat.


15/84


4.6 Standards or Graphical Interaces

When you write a program that provides a graphical user interace, please make it work withthe X Window System and the GTK+ toolkit unless the unctionality specically requires

some alternative (or example, displaying jpeg images while in console mode).In addition, please provide a command-line interace to control the unctionality. (In

many cases, the graphical user interace can be a separate program which invokes thecommand-line program.) This is so that the same jobs can be done rom scripts.

Please also consider providing a D-bus interace or use rom other running programs,such as within GNOME. (GNOME used to use CORBA or this, but that is being phasedout.) In addition, consider providing a library interace (or use rom C), and perhaps akeyboard-driven console interace (or use by users rom console mode). Once you are doingthe work to provide the unctionality and the graphical interace, these wont be much extrawork.

4.7 Standards or Command Line Interaces

It is a good idea to ollow the POSIX guidelines or the command-line options o a program.The easiest way to do this is to use getopt to parse them. Note that the GNU versiono getopt will normally permit options anywhere among the arguments unless the specialargument -- is used. This is not what POSIX species; it is a GNU extension.

Please dene long-named options that are equivalent to the single-letter Unix-style op-tions. We hope to make GNU more user riendly this way. This is easy to do with the GNUunction getopt_long.

One o the advantages o long-named options is that they can be consistent rom programto program. For example, users should be able to expect the verbose option o any GNUprogram which has one, to be spelled precisely --verbose. To achieve this uniormity,

look at the table o common long-option names when you choose the option names or yourprogram (see Section 4.9 [Option Table], page 14).

It is usually a good idea or le names given as ordinary arguments to be input les only;any output les would be specied using options (preerably -o or --output). Even iyou allow an output le name as an ordinary argument or compatibility, try to providean option as another way to speciy it. This will lead to more consistency among GNUutilities, and ewer idiosyncrasies or users to remember.

All programs should support two standard options: --version and --help. CGIprograms should accept these as command-line options, and also i given as the PATH_INFO;or instance, visiting http://example.org/p.cgi/--help in a browser should output thesame inormation as invoking p.cgi --help rom the command line.

4.7.1 --versionThe standard --version option should direct the program to print inormation about itsname, version, origin and legal status, all on standard output, and then exit successully.Other options and arguments should be ignored once this is seen, and the program shouldnot perorm its normal unction.

The rst line is meant to be easy or a program to parse; the version number properstarts ater the last space. In addition, it contains the canonical name or this program, inthis ormat:
http://example.org/p.cgi/--helphttp://example.org/p.cgi/--help


16/84


GNU Emacs 19.30

The programs name should be a constant string; dont compute it rom argv[0]. The ideais to state the standard or canonical name or the program, not its le name. There areother ways to nd out the precise le name where a command is ound in PATH.

I the program is a subsidiary part o a larger package, mention the package name inparentheses, like this:

emacsserver (GNU Emacs) 19.30

I the package has a version number which is diferent rom this programs version number,you can mention the package version number just beore the close-parenthesis.

I you need to mention the version numbers o libraries which are distributed separatelyrom the package which contains this program, you can do so by printing an additional lineo version ino or each library you want to mention. Use the same ormat or these lines asor the rst line.

Please do not mention all o the libraries that the program uses just or completeness

that would produce a lot o unhelpul clutter. Please mention library version numbers onlyi you nd in practice that they are very important to you in debugging.

The ollowing line, ater the version number line or lines, should be a copyright notice.I more than one copyright notice is called or, put each on a separate line.

Next should ollow a line stating the license, preerably using one o abbreviations below,and a brie statement that the program is ree sotware, and that users are ree to copy andchange it. Also mention that there is no warranty, to the extent permitted by law. Seerecommended wording below.

It is ok to nish the output with a list o the major authors o the program, as a way ogiving credit.

Heres an example o output that ollows these rules:

GNU hello 2.3Copyright (C) 2007 Free Software Foundation, Inc.

License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it.There is NO WARRANTY, to the extent permitted by law.

You should adapt this to your program, o course, lling in the proper year, copyrightholder, name o program, and the reerences to distribution terms, and changing the rest othe wording as necessary.

This copyright notice only needs to mention the most recent year in which changes weremadetheres no need to list the years or previous versions changes. You dont have tomention the name o the program in these notices, i that is inconvenient, since it appearedin the rst line. (The rules are diferent or copyright notices in source les; see Section

Copyright Notices in Inormation or GNU Maintainers.)Translations o the above lines must preserve the validity o the copyright notices (see

Section 5.8 [Internationalization], page 40). I the translations character set supports it,the (C) should be replaced with the copyright symbol, as ollows:

c

Write the word Copyright exactly like that, in English. Do not translate it into anotherlanguage. International treaties recognize the English word Copyright; translations intoother languages do not have legal signicance.
http://maintain.pdf/http://maintain.pdf/http://maintain.pdf/http://maintain.pdf/http://maintain.pdf/


17/84


Finally, here is the table o our suggested license abbreviations. Any abbreviation canbe ollowed by vversion[+], meaning that particular version, or later versions with the+, as shown above. In the case o a GNU license, always indicate the permitted versionsin this way.

In the case o exceptions or extra permissions with the GPL, we use / or a separator;the version number can ollow the license abbreviation as usual, as in the examples below.

GPL GNU General Public License, http://www.gnu.org/licenses/gpl.html .

LGPL GNU Lesser General Public License, http://www.gnu.org/licenses/lgpl.html.

GPL/Ada GNU GPL with the exception or Ada.

Apache The Apache Sotware Foundation license, http://www.apache.org/licenses.

Artistic The Artistic license used or Perl, http: / / dev . perl . org / licenses /artistic.html.

Expat The Expat license, http://www.jclark.com/xml/copying.txt.MPL The Mozilla Public License, http://www.mozilla.org/MPL/.

OBSD The original (4-clause) BSD license, incompatible with the GNU GPL http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6 .

PHP The license used or PHP, http://www.php.net/license/.

public domainThe non-license that is being in the public domain, http://www.gnu.org/licenses/license-list.html#PublicDomain .

Python The license or Python, http://www.python.org/2.0.1/license.html .

RBSD The revised (3-clause) BSD, compatible with the GNU GPL,http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5 .

X11 The simple non-copylet license used or most versions o the X Window System,http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3 .

Zlib The license or Zlib, http://www.gzip.org/zlib/zlib_license.html .

More inormation about these licenses and many more are on the GNU licensing webpages, http://www.gnu.org/licenses/license-list.html .

4.7.2 --help

The standard --help option should output brie documentation or how to invoke theprogram, on standard output, then exit successully. Other options and arguments should

be ignored once this is seen, and the program should not perorm its normal unction.Near the end o the --help options output, please place lines giving the email address

or bug reports, the packages home page (normally http://www.gnu.org/software/pkg,and the general page or help using GNU programs. The ormat should be like this:

Report bugs to: mailing-address

pkg home page:

General help using GNU software:

It is ok to mention other appropriate mailing lists and web pages.
http://www.gnu.org/licenses/gpl.htmlhttp://www.gnu.org/licenses/lgpl.htmlhttp://www.gnu.org/licenses/lgpl.htmlhttp://www.apache.org/licenseshttp://dev.perl.org/licenses/artistic.htmlhttp://dev.perl.org/licenses/artistic.htmlhttp://www.jclark.com/xml/copying.txthttp://www.mozilla.org/MPL/http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6http://www.php.net/license/http://www.gnu.org/licenses/license-list.html#PublicDomainhttp://www.gnu.org/licenses/license-list.html#PublicDomainhttp://www.python.org/2.0.1/license.htmlhttp://www.xfree86.org/3.3.6/COPYRIGHT2.html#5http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3http://www.gzip.org/zlib/zlib_license.htmlhttp://www.gnu.org/licenses/license-list.htmlhttp://www.gnu.org/licenses/license-list.htmlhttp://www.gzip.org/zlib/zlib_license.htmlhttp://www.xfree86.org/3.3.6/COPYRIGHT2.html#3http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5http://www.python.org/2.0.1/license.htmlhttp://www.gnu.org/licenses/license-list.html#PublicDomainhttp://www.gnu.org/licenses/license-list.html#PublicDomainhttp://www.php.net/license/http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6http://www.mozilla.org/MPL/http://www.jclark.com/xml/copying.txthttp://dev.perl.org/licenses/artistic.htmlhttp://dev.perl.org/licenses/artistic.htmlhttp://www.apache.org/licenseshttp://www.gnu.org/licenses/lgpl.htmlhttp://www.gnu.org/licenses/lgpl.htmlhttp://www.gnu.org/licenses/gpl.html


18/84


4.8 Standards or Dynamic Plug-in Interaces

Another aspect o keeping ree programs ree is encouraging development o ree plug-ins,and discouraging development o proprietary plug-ins. Many GNU programs will not have

anything like plug-ins at all, but those that do should ollow these practices.First, the general plug-in architecture design should closely tie the plug-in to the original

code, such that the plug-in and the base program are parts o one extended program. ForGCC, or example, plug-ins receive and modiy GCCs internal data structures, and soclearly orm an extended program with the base GCC.

Second, you should require plug-in developers to arm that their plug-ins are releasedunder an appropriate license. This should be enorced with a simple programmatic check.For GCC, again or example, a plug-in must dene the global symbol plugin_is_GPL_compatible, thus asserting that the plug-in is released under a GPL-compatible license(see Section Plugins in GCC Internals).

By adding this check to your program you are not creating a new legal requirement.

The GPL itsel requires plug-ins to be ree sotware, licensed compatibly. As long as youhave ollowed the rst rule above to keep plug-ins closely tied to your original program, theGPL and AGPL already require those plug-ins to be released under a compatible license.The symbol denition in the plug-inor whatever equivalent works best in your programmakes it harder or anyone who might distribute proprietary plug-ins to legally deendthemselves. I a case about this got to court, we can point to that symbol as evidence thatthe plug-in developer understood that the license had this requirement.

4.9 Table o Long Options

Here is a table o long options used by GNU programs. It is surely incomplete, but we aimto list all the options that a new program might want to be compatible with. I you use

names not already in the table, please send [email protected] a list o them, withtheir meanings, so we can update the table.

after-date-N in tar.

all -a in du, ls, nm, stty, uname, and unexpand.

all-text-a in diff.

almost-all-A in ls.

append -a in etags, tee, time; -r in tar.archive -a in cp.

archive-name-n in shar.

arglength-l in m4.

ascii -a in diff.
http://gccint.pdf/http://gccint.pdf/mailto:[email protected]:[email protected]://gccint.pdf/


19/84


assign -v in gawk.

assume-new-W in make.

assume-old-o in make.

auto-check-a in recode.

auto-pager-a in wdiff.

auto-reference-A in ptx.

avoid-wraps-n in wdiff.

backgroundFor server programs, run in the background.

backward-search-B in ctags.

basename-f in shar.

batch Used in GDB.

baud Used in GDB.

before -b in tac.

binary -b in cpio and diff.

bits-per-code-b in shar.

block-sizeUsed in cpio and tar.

blocks -b in head and tail.

break-file-b in ptx.

brief Used in various programs to make output shorter.

bytes -c in head, split, and tail.

c++ -C in etags.

catenate-A in tar.

cd Used in various programs to speciy the directory to use.

changes -c in chgrp and chown.


20/84


classify-F in ls.

colons -c in recode.

command -c in su; -x in GDB.

compare -d in tar.

compat Used in gawk.

compress-Z in tar and shar.

concatenate-A in tar.

confirmation-w in tar.

context Used in diff.

copyleft-W copyleft in gawk.

copyright-C in ptx, recode, and wdiff; -W copyright in gawk.

core Used in GDB.

count -q in who.

count-links

-l in du.create Used in tar and cpio.

cut-mark-c in shar.

cxref -x in ctags.

date -d in touch.

debug -d in make and m4; -t in Bison.

define -D in m4.

defines -d in Bison and ctags.

delete -D in tar.

dereference-L in chgrp, chown, cpio, du, ls, and tar.

dereference-args-D in du.

device Speciy an I/O device (special le name).


21/84


diacritics-d in recode.

dictionary-order

-d in look.diff -d in tar.

digits -n in csplit.

directorySpeciy the directory to use, in various programs. In ls, it means to showdirectories themselves rather than their contents. In rm and ln, it means to nottreat links to directories specially.

discard-all-x in strip.

discard-locals-X in strip.

dry-run -n in make.

ed -e in diff.

elide-empty-files-z in csplit.

end-delete-x in wdiff.

end-insert-z in wdiff.

entire-new-file-N in diff.

environment-overrides-e in make.

eof -e in xargs.

epoch Used in GDB.

error-limitUsed in makeinfo.

error-output-o in m4.

escape -b in ls.

exclude-from-X in tar.

exec Used in GDB.

exit -x in xargs.


22/84


exit-0 -e in unshar.

expand-tabs-t in diff.

expression-e in sed.

extern-only-g in nm.

extract -i in cpio; -x in tar.

faces -f in finger.

fast -f in su.

fatal-warnings-E in m4.

file -f in gawk, info, make, mt, sed, and tar.

field-separator-F in gawk.

file-prefix-b in Bison.

file-type-F in ls.

files-from-T in tar.

fill-columnUsed in makeinfo.

flag-truncation-F in ptx.

fixed-output-files-y in Bison.

follow -f in tail.

footnote-styleUsed in makeinfo.

force -f in cp, ln, mv, and rm.

force-prefix-F in shar.

foregroundFor server programs, run in the oreground; in other words, dont do anythingspecial to run the server in the background.

format Used in ls, time, and ptx.


23/84


freeze-state-F in m4.

fullname

Used in GDB.gap-size

-g in ptx.

get -x in tar.

graphic -i in ul.

graphics-g in recode.

group -g in install.

gzip -z in tar and shar.

hashsize-H in m4.

header -h in objdump and recode

heading -H in who.

help Used to ask or brie usage inormation.

here-delimiter-d in shar.

hide-control-chars-q in ls.

html In makeinfo, output HTML.

idle -u in who.

ifdef -D in diff.

ignore -I in ls; -x in recode.

ignore-all-space-w in diff.

ignore-backups-B in ls.

ignore-blank-lines

-B in diff.

ignore-case-f in look and ptx; -i in diff and wdiff.

ignore-errors-i in make.

ignore-file-i in ptx.


24/84


ignore-indentation-I in etags.

ignore-init-file

-f in Oleo.ignore-interrupts

-i in tee.

ignore-matching-lines-I in diff.

ignore-space-change-b in diff.

ignore-zeros-i in tar.

include -i in etags; -I in m4.include-dir

-I in make.

incremental-G in tar.

info -i, -l, and -m in Finger.

init-fileIn some programs, speciy the name o the le to read as the users init le.

initial -i in expand.

initial-tab-T in diff.

inode -i in ls.

interactive-i in cp, ln, mv, rm; -e in m4; -p in xargs; -w in tar.

intermix-type-p in shar.

iso-8601Used in date

jobs -j in make.

just-print-n in make.

keep-going-k in make.

keep-files-k in csplit.


25/84


kilobytes-k in du and ls.

language

-l in etags.less-mode

-l in wdiff.

level-for-gzip-g in shar.

line-bytes-C in split.

lines Used in split, head, and tail.

link -l in cpio.

lintlint-oldUsed in gawk.

list -t in cpio; -l in recode.

list -t in tar.

literal -N in ls.

load-average-l in make.

login Used in su.

machine Used in uname.

macro-name-M in ptx.

mail -m in hello and uname.

make-directories-d in cpio.

makefile-f in make.

mapped Used in GDB.

max-args

-n in xargs.

max-chars-n in xargs.

max-lines-l in xargs.

max-load-l in make.


26/84


max-procs-P in xargs.

mesg -T in who.

message -T in who.

minimal -d in diff.

mixed-uuencode-M in shar.

mode -m in install, mkdir, and mkfifo.

modification-time-m in tar.

multi-volume-M in tar.

name-prefix-a in Bison.

nesting-limit-L in m4.

net-headers-a in shar.

new-file-W in make.

no-builtin-rules-r in make.

no-character-count-w in shar.

no-check-existing-x in shar.

no-common-3 in wdiff.

no-create-c in touch.

no-defines

-D in etags.

no-deleted-1 in wdiff.

no-dereference-d in cp.

no-inserted-2 in wdiff.


27/84


no-keep-going-S in make.

no-lines

-l in Bison.no-piping

-P in shar.

no-prof -e in gprof.

no-regex-R in etags.

no-sort -p in nm.

no-splashDont print a startup splash screen.

no-splitUsed in makeinfo.

no-static-a in gprof.

no-time -E in gprof.

no-timestamp-m in shar.

no-validateUsed in makeinfo.

no-wait

Used inemacsclient

.no-warn Used in various programs to inhibit warnings.

node -n in info.

nodename-n in uname.

nonmatching-f in cpio.

nstuff -n in objdump.

null -0 in xargs.

number -n in cat.

number-nonblank-b in cat.

numeric-sort-n in nm.

numeric-uid-gid-n in cpio and ls.


28/84


nx Used in GDB.

old-archive-o in tar.

old-file-o in make.

one-file-system-l in tar, cp, and du.

only-file-o in ptx.

only-prof-f in gprof.

only-time

-F in gprof.options -o in getopt, fdlist, fdmount, fdmountd, and fdumount.

output In various programs, speciy the output le name.

output-prefix-o in shar.

override-o in rm.

overwrite-c in unshar.

owner -o in install.paginate

-l in diff.

paragraph-indentUsed in makeinfo.

parents -p in mkdir and rmdir.

pass-all-p in ul.

pass-through

-p in cpio.port -P in finger.

portability-c in cpio and tar.

posix Used in gawk.

prefix-builtins-P in m4.


29/84


prefix -f in csplit.

preserveUsed in tar and cp.

preserve-environment-p in su.

preserve-modification-time-m in cpio.

preserve-order-s in tar.

preserve-permissions-p in tar.

print -l in diff.

print-chars-L in cmp.

print-data-base-p in make.

print-directory-w in make.

print-file-name-o in nm.

print-symdefs-s in nm.

printer -p in wdiff.

prompt -p in ed.

proxy Speciy an HTTP proxy.

query-user-X in shar.

question-q in make.

quiet Used in many programs to inhibit the usual output. Every program accepting--quiet should accept --silent as a synonym.

quiet-unshar-Q in shar

quote-name-Q in ls.

rcs -n in diff.

re-intervalUsed in gawk.


30/84


read-full-blocks-B in tar.

readnow Used in GDB.

recon -n in make.

record-number-R in tar.

recursiveUsed in chgrp, chown, cp, ls, diff, and rm.

reference-r in touch.

references-r in ptx.

regex -r in tac and etags.release -r in uname.

reload-state-R in m4.

relocation-r in objdump.

rename -r in cpio.

replace -i in xargs.

report-identical-files

-s in diff.

reset-access-time-a in cpio.

reverse -r in ls and nm.

reversed-ed-f in diff.

right-side-defs-R in ptx.

same-order

-s in tar.same-permissions

-p in tar.

save -g in stty.

se Used in GDB.

sentence-regexp-S in ptx.


31/84


separate-dirs-S in du.

separator

-s in tac.sequence

Used by recode to chose les or pipes or sequencing passes.

shell -s in su.

show-all-A in cat.

show-c-function-p in diff.

show-ends-E in cat.

show-function-line-F in diff.

show-tabs-T in cat.

silent Used in many programs to inhibit the usual output. Every program accepting--silent should accept --quiet as a synonym.

size -s in ls.

socket Speciy a le descriptor or a network server to use or its socket, instead oopening and binding a new socket. This provides a way to run, in a non-

privileged process, a server that normally needs a reserved port number.

sort Used in ls.

source -W source in gawk.

sparse -S in tar.

speed-large-files-H in diff.

split-at-E in unshar.

split-size-limit

-L in shar.

squeeze-blank-s in cat.

start-delete-w in wdiff.

start-insert-y in wdiff.


32/84


starting-fileUsed in tar and diff to speciy which le within a directory to start processingwith.

statistics-s in wdiff.

stdin-file-list-S in shar.

stop -S in make.

strict -s in recode.

strip -s in install.

strip-all-s in strip.

strip-debug-S in strip.

submitter-s in shar.

suffix -S in cp, ln, mv.

suffix-format-b in csplit.

sum -s in gprof.

summarize-s in du.

symbolic-s in ln.

symbols Used in GDB and objdump.

synclines-s in m4.

sysname -s in uname.

tabs -t in expand and unexpand.

tabsize -T in ls.

terminal -T in tput and ul. -t in wdiff.

text -a in diff.

text-files-T in shar.

time Used in ls and touch.

timeout Speciy how long to wait beore giving up on some operation.


33/84


to-stdout-O in tar.

total -c in du.

touch -t in make, ranlib, and recode.

trace -t in m4.

traditional-t in hello; -W traditional in gawk; -G in ed, m4, and ptx.

tty Used in GDB.

typedefs-t in ctags.

typedefs-and-c++-T in ctags.

typeset-mode-t in ptx.

uncompress-z in tar.

unconditional-u in cpio.

undefine-U in m4.

undefined-only

-u in nm.update -u in cp, ctags, mv, tar.

usage Used in gawk; same as --help.

uuencode-B in shar.

vanilla-operation-V in shar.

verbose Print more inormation about progress. Many programs support this.

verify -W in tar.

version Print the version number.

version-control-V in cp, ln, mv.

vgrind -v in ctags.

volume -V in tar.

what-if -W in make.


34/84


whole-size-limit-l in shar.

width -w in ls and ptx.

word-regexp-W in ptx.

writable-T in who.

zeros -z in gprof.

4.10 OID Allocations

The OID (object identier) 1.3.6.1.4.1.11591 has been assigned to the GNU Project (thanksto Werner Koch). These are used or SNMP, LDAP, X.509 certicates, and so on. Theweb site http://www.alvestrand.no/objectid has a (voluntary) listing o many OID

assignments.

I you need a new slot or your GNU package, write [email protected]. Here is alist o arcs currently assigned:

1.3.6.1.4.1.11591 GNU

1.3.6.1.4.1.11591.1 GNU Radius

1.3.6.1.4.1.11591.2 GnuPG

1.3.6.1.4.1.11591.2.1 notation

1.3.6.1.4.1.11591.2.1.1 pkaAddress

1.3.6.1.4.1.11591.3 GNU Radar

1.3.6.1.4.1.11591.4 GNU GSS

1.3.6.1.4.1.11591.5 GNU Mailutils

1.3.6.1.4.1.11591.6 GNU Shishi

1.3.6.1.4.1.11591.7 GNU Radio

1.3.6.1.4.1.11591.8 GNU Dico

1.3.6.1.4.1.11591.12 digestAlgorithm

1.3.6.1.4.1.11591.12.2 TIGER/192

1.3.6.1.4.1.11591.13 encryptionAlgorithm

1.3.6.1.4.1.11591.13.2 Serpent

1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB

1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC

1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
http://www.alvestrand.no/objectidmailto:[email protected]:[email protected]://www.alvestrand.no/objectid


35/84

Chapter 5: Making The Best Use o C 31

1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB

1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB

1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC

1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB

1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB

1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB

1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC

1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB

1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB

1.3.6.1.4.1.11591.14 CRC algorithms

1.3.6.1.4.1.11591.14.1 CRC 32

4.11 Memory Usage

I a program typically uses just a ew meg o memory, dont bother making any efort to

reduce memory usage. For example, i it is impractical or other reasons to operate on lesmore than a ew meg long, it is reasonable to read entire input les into memory to operateon them.

However, or programs such as cat or tail, that can useully operate on very large les,it is important to avoid using a technique that would articially limit the size o les it canhandle. I a program works by lines and could be applied to arbitrary user-supplied inputles, it should keep only a line in memory, because this is not very hard and users will wantto be able to operate on input les that are bigger than will t in memory all at once.

I your program creates complicated data structures, just make them in memory andgive a atal error i malloc returns zero.

Memory analysis tools such as valgrind can be useul, but dont complicate a programmerely to avoid their alse alarms. For example, i memory is used until just beore a processexits, dont ree it simply to silence such a tool.

4.12 File Usage

Programs should be prepared to operate when /usr and /etc are read-only le systems.Thus, i the program manages log les, lock les, backup les, score les, or any other leswhich are modied or internal purposes, these les should not be stored in /usr or /etc.

There are two exceptions. /etc is used to store system conguration inormation; it isreasonable or a program to modiy les in /etc when its job is to update the system con-

guration. Also, i the user explicitly asks to modiy one le in a directory, it is reasonableor the program to store other les in the same directory.

5 Making The Best Use o C

This chapter provides advice on how best to use the C language when writing GNU sotware.


36/84


5.1 Formatting Your Source Code

It is important to put the open-brace that starts the body o a C unction in column one,so that they will start a deun. Several tools look or open-braces in column one to nd the

beginnings o C unctions. These tools will not work on code not ormatted that way.Avoid putting open-brace, open-parenthesis or open-bracket in column one when they

are inside a unction, so that they wont start a deun. The open-brace that starts a structbody can go in column one i you nd it useul to treat that denition as a deun.

It is also important or unction denitions to start the name o the unction in columnone. This helps people to search or unction denitions, and may also help certain toolsrecognize them. Thus, using Standard C syntax, the ormat is this:

static char *

concat (char *s1, char *s2)

{

...

}

or, i you want to use traditional C syntax, ormat the denition like this:

static char *

concat (s1, s2) /* Name starts in column one here */

char *s1, *s2;

{ /* Open brace in column one here */

...

}

In Standard C, i the arguments dont t nicely on one line, split it like this:

int

lots_of_args (int an_integer, long a_long, short a_short,

double a_double, float a_float)

...

For struct and enum types, likewise put the braces in column one, unless the wholecontents ts on one line:

struct foo

{

int a, b;

}

or

struct foo { int a, b; }The rest o this section gives our recommendations or other aspects o C ormatting

style, which is also the deault style o the indent program in version 1.2 and newer. Itcorresponds to the options

-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob

We dont think o these recommendations as requirements, because it causes no problemsor users i two diferent programs have diferent ormatting styles.


37/84


But whatever style you use, please use it consistently, since a mixture o styles withinone program tends to look ugly. I you are contributing changes to an existing program,please ollow the style o that program.

For the body o the unction, our recommended style looks like this:if (x < foo (y, z))

haha = bar[4] + 5;

else

{

while (z)

{

haha += foo (z, z);

z--;

}

return ++x + bar ();

}

We nd it easier to read a program when it has spaces beore the open-parentheses andater the commas. Especially ater the commas.

When you split an expression into multiple lines, split it beore an operator, not aterone. Here is the right way:

if (foo_this_is_long && bar > win (x, y, z)

&& remaining_condition)

Try to avoid having two operators o diferent precedence at the same level o indentation.For example, dont write this:

mode = (inmode[j] == VOIDmode

|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])

? outmode[j] : inmode[j]);Instead, use extra parentheses so that the indentation shows the nesting:

mode = ((inmode[j] == VOIDmode

|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))

? outmode[j] : inmode[j]);

Insert extra parentheses so that Emacs will indent the code properly. For example, theollowing indentation looks nice i you do it by hand,

v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000

+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;

but Emacs would alter it. Adding a set o parentheses produces something that looks

equally nice, and which Emacs will preserve:v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000

+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);

Format do-while statements like this:

do

{

a = foo (a);

}


38/84


while (a > 0);

Please use ormeed characters (control-L) to divide the program into pages at logicalplaces (but not within a unction). It does not matter just how long the pages are, since

they do not have to t on a printed page. The ormeeds should appear alone on lines bythemselves.

5.2 Commenting Your Work

Every program should start with a comment saying briey what it is or. Example: fmt- filter for simple filling of text. This comment should be at the top o the sourcele containing the main unction o the program.

Also, please write a brie comment at the start o each source le, with the le nameand a line or two about the overall purpose o the le.

Please write the comments in a GNU program in English, because English is the onelanguage that nearly all programmers in all countries can read. I you do not write English

well, please write comments in English as well as you can, then ask other people to helprewrite them. I you cant write comments in English, please nd someone to work withyou and translate your comments into English.

Please put a comment on each unction saying what the unction does, what sorts oarguments it gets, and what the possible values o arguments mean and are used or. Itis not necessary to duplicate in words the meaning o the C argument declarations, i a Ctype is being used in its customary ashion. I there is anything nonstandard about its use(such as an argument o type char * which is really the address o the second character o astring, not the rst), or any possible values that would not work the way one would expect(such as, that strings containing newlines are not guaranteed to work), be sure to say so.

Also explain the signicance o the return value, i there is one.

Please put two spaces ater the end o a sentence in your comments, so that the Emacssentence commands will work. Also, please write complete sentences and capitalize the rstword. I a lower-case identier comes at the beginning o a sentence, dont capitalize it!Changing the spelling makes it a diferent identier. I you dont like starting a sentencewith a lower case letter, write the sentence diferently (e.g., The identier lower-case is. . . ).

The comment on a unction is much clearer i you use the argument names to speakabout the argument values. The variable name itsel should be lower case, but write it inupper case when you are speaking about the value rather than the variable itsel. Thus,the inode number NODE NUM rather than an inode.

There is usually no purpose in restating the name o the unction in the comment beore

it, because readers can see that or themselves. There might be an exception when thecomment is so long that the unction itsel would be of the bottom o the screen.

There should be a comment on each static variable as well, like this:

/* Nonzero means truncate lines in the display;

zero means continue them. */

int truncate_lines;

Every #endif should have a comment, except in the case o short conditionals (just aew lines) that are not nested. The comment should state the condition o the conditional


39/84


that is ending, including its sense. #else should have a comment describing the conditionand sense o the code that ollows. For example:

#ifdef foo

...

#else /* not foo */

...

#endif /* not foo */

#ifdef foo

...

#endif /* foo */

but, by contrast, write the comments this way or a #ifndef:

#ifndef foo

...

#else /* foo */

...

#endif /* foo */

#ifndef foo

...

#endif /* not foo */

5.3 Clean Use o C Constructs

Please explicitly declare the types o all objects. For example, you should explicitly declareall arguments to unctions, and you should declare unctions to return int rather thanomitting the int.

Some programmers like to use the GCC -Wall option, and change the code wheneverit issues a warning. I you want to do this, then do. Other programmers preer not to use-Wall, because it gives warnings or valid and legitimate code which they do not want tochange. I you want to do this, then do. The compiler should be your servant, not yourmaster.

Dont make the program ugly just to placate static analysis tools such as lint, clang,and GCC with extra warnings options such as -Wconversion and -Wundef. These tools canhelp nd bugs and unclear code, but they can also generate so many alse alarms that ithurts readability to silence them with unnecessary casts, wrappers, and other complications.For example, please dont insert casts to void or calls to do-nothing unctions merely topaciy a lint checker.

Declarations o external unctions and unctions to appear later in the source le shouldall go in one place near the beginning o the le (somewhere beore the rst unction

denition in the le), or else should go in a header le. Dont put extern declarationsinside unctions.

It used to be common practice to use the same local variables (with names like tem) overand over or diferent values within one unction. Instead o doing this, it is better to declarea separate local variable or each distinct purpose, and give it a name which is meaningul.This not only makes programs easier to understand, it also acilitates optimization by goodcompilers. You can also move the declaration o each local variable into the smallest scopethat includes all its uses. This makes the program even cleaner.


40/84


Dont use local variables or parameters that shadow global identiers. GCCs -Wshadowoption can detect this problem.

Dont declare multiple variables in one declaration that spans lines. Start a new decla-

ration on each line, instead. For example, instead o this:int foo,

bar;

write either this:

int foo, bar;

or this:

int foo;

int bar;

(I they are global variables, each should have a comment preceding it anyway.)

When you have an if-else statement nested in another if statement, always put bracesaround the if-else. Thus, never write like this:

if (foo)

if (bar)

win ();

else

lose ();

always like this:

if (foo)

{

if (bar)

win ();else

lose ();

}

I you have an if statement nested inside o an else statement, either write else if onone line, like this,

if (foo)

...

else if (bar)

...

with its then-part indented like the preceding then-part, or write the nested if within

braces like this:

if (foo)

...

else

{

if (bar)

...

}


41/84


Dont declare both a structure tag and variables or typedes in the same declaration.Instead, declare the structure tag separately and then use it to declare the variables ortypedes.

Try to avoid assignments inside if-conditions (assignments inside while-conditions areok). For example, dont write this:

if ((foo = (char *) malloc (sizeof *foo)) == 0)

fatal ("virtual memory exhausted");

instead, write this:

foo = (char *) malloc (sizeof *foo);

if (foo == 0)

fatal ("virtual memory exhausted");

This example uses zero without a cast as a null pointer constant. This is perectly ne,except that a cast is needed when calling a varargs unction or when using sizeof.

5.4 Naming Variables, Functions, and FilesThe names o global variables and unctions in a program serve as comments o a sort. Sodont choose terse namesinstead, look or names that give useul inormation about themeaning o the variable or unction. In a GNU program, names should be English, likeother comments.

Local variable names can be shorter, because they are used only within one context,where (presumably) comments explain their purpose.

Try to limit your use o abbreviations in symbol names. It is ok to make a ew abbrevia-tions, explain what they mean, and then use them requently, but dont use lots o obscureabbreviations.

Please use underscores to separate words in a name, so that the Emacs word commandscan be useul within them. Stick to lower case; reserve upper case or macros and enumconstants, and or name-prexes that ollow a uniorm convention.

For example, you should use names like ignore_space_change_flag; dont use nameslike iCantReadThis.

Variables that indicate whether command-line options have been specied should benamed ater the meaning o the option, not ater the option-letter. A comment should stateboth the exact meaning o the option and its letter. For example,

/* Ignore changes in horizontal whitespace (-b). */

int ignore_space_change_flag;

When you want to dene names with constant integer values, use enum rather than

#define. GDB knows about enumeration constants.You might want to make sure that none o the le names would conict i the les were

loaded onto an MS-DOS le system which shortens the names. You can use the programdoschk to test or this.

Some GNU programs were designed to limit themselves to le names o 14 charactersor less, to avoid le name conicts i they are read into older System V systems. Pleasepreserve this eature in the existing GNU programs that have it, but there is no need to dothis in new GNU programs. doschk also reports le names longer than 14 characters.


42/84


5.5 Portability between System Types

In the Unix world, portability reers to porting to diferent Unix versions. For a GNUprogram, this kind o portability is desirable, but not paramount.

The primary purpose o GNU sotware is to run on top o the GNU kernel, compiledwith the GNU C compiler, on various types o CPU. So the kinds o portability that areabsolutely necessary are quite limited. But it is important to support Linux-based GNUsystems, since they are the orm o GNU that is popular.

Beyond that, it is good to support the other ree operating systems (*BSD), and it isnice to support other Unix-like systems i you want to. Supporting a variety o Unix-likesystems is desirable, although not paramount. It is usually not too hard, so you may aswell do it. But you dont have to consider it an obligation, i it does turn out to be hard.

The easiest way to achieve portability to most Unix-like systems is to use Autocon. Itsunlikely that your program needs to know more inormation about the host platorm thanAutocon can provide, simply because most o the programs that need such knowledge have

already been written.Avoid using the ormat o semi-internal data bases (e.g., directories) when there is a

higher-level alternative (readdir).

As or systems that are not like Unix, such as MSDOS, Windows, VMS, MVS, and olderMacintosh systems, supporting them is oten a lot o work. When that is the case, it isbetter to spend your time adding eatures that will be useul on GNU and GNU/Linux,rather than on supporting other incompatible systems.

I you do support Windows, please do not abbreviate it as win. In hacker terminology,calling something a win is a orm o praise. Youre ree to praise Microsot Windows onyour own i you want, but please dont do this in GNU packages. Instead o abbreviatingWindows to win, you can write it in ull or abbreviate it to woe or w. In GNU

Emacs, or instance, we use w32 in le names o Windows-specic les, but the macro orWindows conditionals is called WINDOWSNT.

It is a good idea to dene the eature test macro _GNU_SOURCE when compiling yourC les. When you compile on GNU or GNU/Linux, this will enable the declarations oGNU library extension unctions, and that will usually give you a compiler error message iyou dene the same unction names in some other way in your program. (You dont haveto actually use these unctions, i you preer to make the program more portable to othersystems.)

But whether or not you use these GNU extensions, you should avoid using their namesor any other meanings. Doing so would make it hard to move your code into other GNUprograms.

5.6 Portability between CPUs

Even GNU systems will difer because o diferences among CPU typesor example, di-erence in byte ordering and alignment requirements. It is absolutely essential to handlethese diferences. However, dont make any efort to cater to the possibility that an intwill be less than 32 bits. We dont support 16-bit machines in GNU.

Similarly, dont make any efort to cater to the possibility that long will be smaller thanpredened types like size_t. For example, the ollowing code is ok:


43/84


printf ("size = %lu\n", (unsigned long) sizeof array);

printf ("diff = %ld\n", (long) (pointer2 - pointer1));

1989 Standard C requires this to work, and we know o only one counterexample: 64-bitprograms on Microsot Windows. We will leave it to those who want to port GNU programsto that environment to gure out how to do it.

Predened le-size types like off_t are an exception: they are longer than long on manyplatorms, so code like the above wont work with them. One way to print an off_t valueportably is to print its digits yoursel, one by one.

Dont assume that the address o an int object is also the address o its least-signicantbyte. This is alse on big-endian machines. Thus, dont make the ollowing mistake:

int c;

...

while ((c = getchar ()) != EOF)

write (file_descriptor, &c, 1);

Instead, use unsigned char as ollows. (The unsigned is or portability to unusual systemswhere char is signed and where there is integer overow checking.)

int c;

while ((c = getchar ()) != EOF)

{

unsigned char u = c;

write (file_descriptor, &u, 1);

}

Avoid casting pointers to integers i you can. Such casts greatly reduce portability, andin most programs they are easy to avoid. In the cases where casting pointers to integers isessentialsuch as, a Lisp interpreter which stores type inormation as well as an address inone wordyoull have to make explicit provisions to handle diferent word sizes. You willalso need to make provision or systems in which the normal range o addresses you can getrom malloc starts ar away rom zero.

5.7 Calling System Functions

Historically, C implementations difered substantially, and many systems lacked a ull im-plementation o ANSI/ISO C89. Nowadays, however, all practical systems have a C89compiler and GNU C supports almost all o C99 and some o C11. Similarly, most systemsimplement POSIX.1-2001 libraries and tools, and many have POSIX.1-2008.

Hence, there is little reason to support old C or non-POSIX systems, and you maywant to take advantage o standard C and POSIX to write clearer, more portable, or astercode. You should use standard interaces where possible; but i GNU extensions make yourprogram more maintainable, powerul, or otherwise better, dont hesitate to use them. Inany case, dont make your own declaration o system unctions; thats a recipe or conict.

Despite the standards, nearly every library unction has some sort o portability issueon some system or another. Here are some examples:

open Names with trailing /s are mishandled on many platorms.

printf long double may be unimplemented; oating values Innity and NaN are otenmishandled; output or large precisions may be incorrect.


44/84


readlink May return int instead o ssize_t.

scanf On Windows, errno is not set on ailure.

Gnulib is a big help in this regard. Gnulib provides implementations o standard in-teraces on many o the systems that lack them, including portable implementations oenhanced GNU interaces, thereby making their use portable, and o POSIX-1.2008 inter-aces, some o which are missing even on up-to-date GNU systems.

Gnulib also provides many useul non-standard interaces; or example, C implemen-tations o standard data structures (hash tables, binary trees), error-checking ty

gnu coding standards

Documents