Subversion Repositories openrisc

\input texinfo @c -*-texinfo-*-

\input texinfo @c -*-texinfo-*-

@c %**start of header

@c %**start of header

@setfilename standards.info

@setfilename standards.info

@settitle GNU Coding Standards

@settitle GNU Coding Standards

@c This date is automagically updated when you save this file:

@c This date is automagically updated when you save this file:

@set lastupdate July 22, 2007

@set lastupdate July 22, 2007

@c %**end of header

@c %**end of header

@dircategory GNU organization

@dircategory GNU organization

@direntry

@direntry

* Standards: (standards).         GNU coding standards.

* Standards: (standards).         GNU coding standards.

@end direntry

@end direntry

@c @setchapternewpage odd

@c @setchapternewpage odd

@setchapternewpage off

@setchapternewpage off

@c Put everything in one index (arbitrarily chosen to be the concept index).

@c Put everything in one index (arbitrarily chosen to be the concept index).

@syncodeindex fn cp

@syncodeindex fn cp

@syncodeindex ky cp

@syncodeindex ky cp

@syncodeindex pg cp

@syncodeindex pg cp

@syncodeindex vr cp

@syncodeindex vr cp

@c This is used by a cross ref in make-stds.texi

@c This is used by a cross ref in make-stds.texi

@set CODESTD  1

@set CODESTD  1

@iftex

@iftex

@set CHAPTER chapter

@set CHAPTER chapter

@end iftex

@end iftex

@ifinfo

@ifinfo

@set CHAPTER node

@set CHAPTER node

@end ifinfo

@end ifinfo

@copying

@copying

The GNU coding standards, last updated @value{lastupdate}.

The GNU coding standards, last updated @value{lastupdate}.

Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,

Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,

2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software

2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software

Foundation, Inc.

Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.2

under the terms of the GNU Free Documentation License, Version 1.2

or any later version published by the Free Software Foundation;

or any later version published by the Free Software Foundation;

with no Invariant Sections, with no

with no Invariant Sections, with no

Front-Cover Texts, and with no Back-Cover Texts.

Front-Cover Texts, and with no Back-Cover Texts.

A copy of the license is included in the section entitled ``GNU

A copy of the license is included in the section entitled ``GNU

Free Documentation License''.

Free Documentation License''.

@end copying

@end copying

@titlepage

@titlepage

@title GNU Coding Standards

@title GNU Coding Standards

@author Richard Stallman, et al.

@author Richard Stallman, et al.

@author last updated @value{lastupdate}

@author last updated @value{lastupdate}

@page

@page

@vskip 0pt plus 1filll

@vskip 0pt plus 1filll

@insertcopying

@insertcopying

@end titlepage

@end titlepage

@contents

@contents

@ifnottex

@ifnottex

@node Top, Preface, (dir), (dir)

@node Top, Preface, (dir), (dir)

@top Version

@top Version

@insertcopying

@insertcopying

@end ifnottex

@end ifnottex

@menu

@menu

* Preface::                     About the GNU Coding Standards.

* Preface::                     About the GNU Coding Standards.

* Legal Issues::                Keeping free software free.

* Legal Issues::                Keeping free software free.

* Design Advice::               General program design.

* Design Advice::               General program design.

* Program Behavior::            Program behavior for all programs

* Program Behavior::            Program behavior for all programs

* Writing C::                   Making the best use of C.

* Writing C::                   Making the best use of C.

* Documentation::               Documenting programs.

* Documentation::               Documenting programs.

* Managing Releases::           The release process.

* Managing Releases::           The release process.

* References::                  Mentioning non-free software or documentation.

* References::                  Mentioning non-free software or documentation.

* GNU Free Documentation License::  Copying and sharing this manual.

* GNU Free Documentation License::  Copying and sharing this manual.

* Index::

* Index::

@end menu

@end menu

@node Preface

@node Preface

@chapter About the GNU Coding Standards

@chapter About the GNU Coding Standards

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

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

Project volunteers.  Their purpose is to make the GNU system clean,

Project volunteers.  Their purpose is to make the GNU system clean,

consistent, and easy to install.  This document can also be read as a

consistent, and easy to install.  This document can also be read as a

guide to writing portable, robust and reliable programs.  It focuses on

guide to writing portable, robust and reliable programs.  It focuses on

programs written in C, but many of the rules and principles are useful

programs written in C, but many of the rules and principles are useful

even if you write in another programming language.  The rules often

even if you write in another programming language.  The rules often

state reasons for writing in a certain way.

state reasons for writing in a certain way.

This release of the GNU Coding Standards was last updated

This release of the GNU Coding Standards was last updated

@value{lastupdate}.

@value{lastupdate}.

@cindex where to obtain @code{standards.texi}

@cindex where to obtain @code{standards.texi}

@cindex downloading this manual

@cindex downloading this manual

If you did not obtain this file directly from the GNU project and

If you did not obtain this file directly from the GNU project and

recently, please check for a newer version.  You can get the GNU

recently, please check for a newer version.  You can get the GNU

Coding Standards from the GNU web server in many

Coding Standards from the GNU web server in many

different formats, including the Texinfo source, PDF, HTML, DVI, plain

different formats, including the Texinfo source, PDF, HTML, DVI, plain

text, and more, at: @uref{http://www.gnu.org/prep/standards/}.

text, and more, at: @uref{http://www.gnu.org/prep/standards/}.

Corrections or suggestions for this document should be sent to

Corrections or suggestions for this document should be sent to

@email{bug-standards@@gnu.org}.  If you make a suggestion, please include a

@email{bug-standards@@gnu.org}.  If you make a suggestion, please include a

suggested new wording for it; our time is limited.  We prefer a context

suggested new wording for it; our time is limited.  We prefer a context

diff to the @file{standards.texi} or @file{make-stds.texi} files, but if

diff to the @file{standards.texi} or @file{make-stds.texi} files, but if

you don't have those files, please mail your suggestion anyway.

you don't have those files, please mail your suggestion anyway.

These standards cover the minimum of what is important when writing a

These standards cover the minimum of what is important when writing a

GNU package.  Likely, the need for additional standards will come up.

GNU package.  Likely, the need for additional standards will come up.

Sometimes, you might suggest that such standards be added to this

Sometimes, you might suggest that such standards be added to this

document.  If you think your standards would be generally useful, please

document.  If you think your standards would be generally useful, please

do suggest them.

do suggest them.

You should also set standards for your package on many questions not

You should also set standards for your package on many questions not

addressed or not firmly specified here.  The most important point is to

addressed or not firmly specified here.  The most important point is to

be self-consistent---try to stick to the conventions you pick, and try

be self-consistent---try to stick to the conventions you pick, and try

to document them as much as possible.  That way, your program will be

to document them as much as possible.  That way, your program will be

more maintainable by others.

more maintainable by others.

The GNU Hello program serves as an example of how to follow the GNU

The GNU Hello program serves as an example of how to follow the GNU

coding standards for a trivial program.

coding standards for a trivial program.

@uref{http://www.gnu.org/software/hello/hello.html}.

@uref{http://www.gnu.org/software/hello/hello.html}.

@node Legal Issues

@node Legal Issues

@chapter Keeping Free Software Free

@chapter Keeping Free Software Free

@cindex legal aspects

@cindex legal aspects

This chapter discusses how you can make sure that GNU software

This chapter discusses how you can make sure that GNU software

avoids legal difficulties, and other related issues.

avoids legal difficulties, and other related issues.

@menu

@menu

* Reading Non-Free Code::       Referring to proprietary programs.

* Reading Non-Free Code::       Referring to proprietary programs.

* Contributions::               Accepting contributions.

* Contributions::               Accepting contributions.

* Trademarks::                  How we deal with trademark issues.

* Trademarks::                  How we deal with trademark issues.

@end menu

@end menu

@node Reading Non-Free Code

@node Reading Non-Free Code

@section Referring to Proprietary Programs

@section Referring to Proprietary Programs

@cindex proprietary programs

@cindex proprietary programs

@cindex avoiding proprietary code

@cindex avoiding proprietary code

Don't in any circumstances refer to Unix source code for or during

Don't in any circumstances refer to Unix source code for or during

your work on GNU!  (Or to any other proprietary programs.)

your work on GNU!  (Or to any other proprietary programs.)

If you have a vague recollection of the internals of a Unix program,

If you have a vague recollection of the internals of a Unix program,

this does not absolutely mean you can't write an imitation of it, but

this does not absolutely mean you can't write an imitation of it, but

do try to organize the imitation internally along different lines,

do try to organize the imitation internally along different lines,

because this is likely to make the details of the Unix version

because this is likely to make the details of the Unix version

irrelevant and dissimilar to your results.

irrelevant and dissimilar to your results.

For example, Unix utilities were generally optimized to minimize

For example, Unix utilities were generally optimized to minimize

memory use; if you go for speed instead, your program will be very

memory use; if you go for speed instead, your program will be very

different.  You could keep the entire input file in memory and scan it

different.  You could keep the entire input file in memory and scan it

there instead of using stdio.  Use a smarter algorithm discovered more

there instead of using stdio.  Use a smarter algorithm discovered more

recently than the Unix program.  Eliminate use of temporary files.  Do

recently than the Unix program.  Eliminate use of temporary files.  Do

it in one pass instead of two (we did this in the assembler).

it in one pass instead of two (we did this in the assembler).

Or, on the contrary, emphasize simplicity instead of speed.  For some

Or, on the contrary, emphasize simplicity instead of speed.  For some

applications, the speed of today's computers makes simpler algorithms

applications, the speed of today's computers makes simpler algorithms

adequate.

adequate.

Or go for generality.  For example, Unix programs often have static

Or go for generality.  For example, Unix programs often have static

tables or fixed-size strings, which make for arbitrary limits; use

tables or fixed-size strings, which make for arbitrary limits; use

dynamic allocation instead.  Make sure your program handles NULs and

dynamic allocation instead.  Make sure your program handles NULs and

other funny characters in the input files.  Add a programming language

other funny characters in the input files.  Add a programming language

for extensibility and write part of the program in that language.

for extensibility and write part of the program in that language.

Or turn some parts of the program into independently usable libraries.

Or turn some parts of the program into independently usable libraries.

Or use a simple garbage collector instead of tracking precisely when

Or use a simple garbage collector instead of tracking precisely when

to free memory, or use a new GNU facility such as obstacks.

to free memory, or use a new GNU facility such as obstacks.

@node Contributions

@node Contributions

@section Accepting Contributions

@section Accepting Contributions

@cindex legal papers

@cindex legal papers

@cindex accepting contributions

@cindex accepting contributions

If the program you are working on is copyrighted by the Free Software

If the program you are working on is copyrighted by the Free Software

Foundation, then when someone else sends you a piece of code to add to

Foundation, then when someone else sends you a piece of code to add to

the program, we need legal papers to use it---just as we asked you to

the program, we need legal papers to use it---just as we asked you to

sign papers initially.  @emph{Each} person who makes a nontrivial

sign papers initially.  @emph{Each} person who makes a nontrivial

contribution to a program must sign some sort of legal papers in order

contribution to a program must sign some sort of legal papers in order

for us to have clear title to the program; the main author alone is not

for us to have clear title to the program; the main author alone is not

enough.

enough.

So, before adding in any contributions from other people, please tell

So, before adding in any contributions from other people, please tell

us, so we can arrange to get the papers.  Then wait until we tell you

us, so we can arrange to get the papers.  Then wait until we tell you

that we have received the signed papers, before you actually use the

that we have received the signed papers, before you actually use the

contribution.

contribution.

This applies both before you release the program and afterward.  If

This applies both before you release the program and afterward.  If

you receive diffs to fix a bug, and they make significant changes, we

you receive diffs to fix a bug, and they make significant changes, we

need legal papers for that change.

need legal papers for that change.

This also applies to comments and documentation files.  For copyright

This also applies to comments and documentation files.  For copyright

law, comments and code are just text.  Copyright applies to all kinds of

law, comments and code are just text.  Copyright applies to all kinds of

text, so we need legal papers for all kinds.

text, so we need legal papers for all kinds.

We know it is frustrating to ask for legal papers; it's frustrating for

We know it is frustrating to ask for legal papers; it's frustrating for

us as well.  But if you don't wait, you are going out on a limb---for

us as well.  But if you don't wait, you are going out on a limb---for

example, what if the contributor's employer won't sign a disclaimer?

example, what if the contributor's employer won't sign a disclaimer?

You might have to take that code out again!

You might have to take that code out again!

You don't need papers for changes of a few lines here or there, since

You don't need papers for changes of a few lines here or there, since

they are not significant for copyright purposes.  Also, you don't need

they are not significant for copyright purposes.  Also, you don't need

papers if all you get from the suggestion is some ideas, not actual code

papers if all you get from the suggestion is some ideas, not actual code

which you use.  For example, if someone sent you one implementation, but

which you use.  For example, if someone sent you one implementation, but

you write a different implementation of the same idea, you don't need to

you write a different implementation of the same idea, you don't need to

get papers.

get papers.

The very worst thing is if you forget to tell us about the other

The very worst thing is if you forget to tell us about the other

contributor.  We could be very embarrassed in court some day as a

contributor.  We could be very embarrassed in court some day as a

result.

result.

We have more detailed advice for maintainers of programs; if you have

We have more detailed advice for maintainers of programs; if you have

reached the stage of actually maintaining a program for GNU (whether

reached the stage of actually maintaining a program for GNU (whether

released or not), please ask us for a copy.  It is also available

released or not), please ask us for a copy.  It is also available

online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.

online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.

@node Trademarks

@node Trademarks

@section Trademarks

@section Trademarks

@cindex trademarks

@cindex trademarks

Please do not include any trademark acknowledgements in GNU software

Please do not include any trademark acknowledgements in GNU software

packages or documentation.

packages or documentation.

Trademark acknowledgements are the statements that such-and-such is a

Trademark acknowledgements are the statements that such-and-such is a

trademark of so-and-so.  The GNU Project has no objection to the basic

trademark of so-and-so.  The GNU Project has no objection to the basic

idea of trademarks, but these acknowledgements feel like kowtowing,

idea of trademarks, but these acknowledgements feel like kowtowing,

and there is no legal requirement for them, so we don't use them.

and there is no legal requirement for them, so we don't use them.

What is legally required, as regards other people's trademarks, is to

What is legally required, as regards other people's trademarks, is to

avoid using them in ways which a reader might reasonably understand as

avoid using them in ways which a reader might reasonably understand as

naming or labeling our own programs or activities.  For example, since

naming or labeling our own programs or activities.  For example, since

``Objective C'' is (or at least was) a trademark, we made sure to say

``Objective C'' is (or at least was) a trademark, we made sure to say

that we provide a ``compiler for the Objective C language'' rather

that we provide a ``compiler for the Objective C language'' rather

than an ``Objective C compiler''.  The latter would have been meant as

than an ``Objective C compiler''.  The latter would have been meant as

a shorter way of saying the former, but it does not explicitly state

a shorter way of saying the former, but it does not explicitly state

the relationship, so it could be misinterpreted as using ``Objective

the relationship, so it could be misinterpreted as using ``Objective

C'' as a label for the compiler rather than for the language.

C'' as a label for the compiler rather than for the language.

Please don't use ``win'' as an abbreviation for Microsoft Windows in

Please don't use ``win'' as an abbreviation for Microsoft Windows in

GNU software or documentation.  In hacker terminology, calling

GNU software or documentation.  In hacker terminology, calling

something a ``win'' is a form of praise.  If you wish to praise

something a ``win'' is a form of praise.  If you wish to praise

Microsoft Windows when speaking on your own, by all means do so, but

Microsoft Windows when speaking on your own, by all means do so, but

not in GNU software.  Usually we write the name ``Windows'' in full,

not in GNU software.  Usually we write the name ``Windows'' in full,

but when brevity is very important (as in file names and sometimes

but when brevity is very important (as in file names and sometimes

symbol names), we abbreviate it to ``w''.  For instance, the files and

symbol names), we abbreviate it to ``w''.  For instance, the files and

functions in Emacs that deal with Windows start with @samp{w32}.

functions in Emacs that deal with Windows start with @samp{w32}.

@node Design Advice

@node Design Advice

@chapter General Program Design

@chapter General Program Design

@cindex program design

@cindex program design

This chapter discusses some of the issues you should take into

This chapter discusses some of the issues you should take into

account when designing your program.

account when designing your program.

@c                         Standard or ANSI C

@c                         Standard or ANSI C

@c

@c

@c In 1989 the American National Standards Institute (ANSI) standardized

@c In 1989 the American National Standards Institute (ANSI) standardized

@c C   as  standard  X3.159-1989.    In  December   of  that   year  the

@c C   as  standard  X3.159-1989.    In  December   of  that   year  the

@c International Standards Organization ISO  adopted the ANSI C standard

@c International Standards Organization ISO  adopted the ANSI C standard

@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard

@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard

@c C. This version of C is known as either ANSI C or Standard C.

@c C. This version of C is known as either ANSI C or Standard C.

@c A major revision of the C Standard appeared in 1999.

@c A major revision of the C Standard appeared in 1999.

@menu

@menu

* Source Language::             Which languages to use.

* Source Language::             Which languages to use.

* Compatibility::               Compatibility with other implementations.

* Compatibility::               Compatibility with other implementations.

* Using Extensions::            Using non-standard features.

* Using Extensions::            Using non-standard features.

* Standard C::                  Using standard C features.

* Standard C::                  Using standard C features.

* Conditional Compilation::     Compiling code only if a conditional is true.

* Conditional Compilation::     Compiling code only if a conditional is true.

@end menu

@end menu

@node Source Language

@node Source Language

@section Which Languages to Use

@section Which Languages to Use

@cindex programming languages

@cindex programming languages

When you want to use a language that gets compiled and runs at high

When you want to use a language that gets compiled and runs at high

speed, the best language to use is C.  Using another language is like

speed, the best language to use is C.  Using another language is like

using a non-standard feature: it will cause trouble for users.  Even if

using a non-standard feature: it will cause trouble for users.  Even if

GCC supports the other language, users may find it inconvenient to have

GCC supports the other language, users may find it inconvenient to have

to install the compiler for that other language in order to build your

to install the compiler for that other language in order to build your

program.  For example, if you write your program in C++, people will

program.  For example, if you write your program in C++, people will

have to install the GNU C++ compiler in order to compile your program.

have to install the GNU C++ compiler in order to compile your program.

C has one other advantage over C++ and other compiled languages: more

C has one other advantage over C++ and other compiled languages: more

people know C, so more people will find it easy to read and modify the

people know C, so more people will find it easy to read and modify the

program if it is written in C.

program if it is written in C.

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

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

comparable alternatives.

comparable alternatives.

But there are two exceptions to that conclusion:

But there are two exceptions to that conclusion:

@itemize @bullet

@itemize @bullet

@item

@item

It is no problem to use another language to write a tool specifically

It is no problem to use another language to write a tool specifically

intended for use with that language.  That is because the only people

intended for use with that language.  That is because the only people

who want to build the tool will be those who have installed the other

who want to build the tool will be those who have installed the other

language anyway.

language anyway.

@item

@item

If an application is of interest only to a narrow part of the community,

If an application is of interest only to a narrow part of the community,

then the question of which language it is written in has less effect on

then the question of which language it is written in has less effect on

other people, so you may as well please yourself.

other people, so you may as well please yourself.

@end itemize

@end itemize

Many programs are designed to be extensible: they include an interpreter

Many programs are designed to be extensible: they include an interpreter

for a language that is higher level than C.  Often much of the program

for a language that is higher level than C.  Often much of the program

is written in that language, too.  The Emacs editor pioneered this

is written in that language, too.  The Emacs editor pioneered this

technique.

technique.

@cindex GUILE

@cindex GUILE

The standard extensibility interpreter for GNU software is GUILE

The standard extensibility interpreter for GNU software is GUILE

(@uref{http://www.gnu.org/software/guile/}), which implements the

(@uref{http://www.gnu.org/software/guile/}), which implements the

language Scheme (an especially clean and simple dialect of Lisp).  We

language Scheme (an especially clean and simple dialect of Lisp).  We

don't reject programs written in other ``scripting languages'' such as

don't reject programs written in other ``scripting languages'' such as

Perl and Python, but using GUILE is very important for the overall

Perl and Python, but using GUILE is very important for the overall

consistency of the GNU system.

consistency of the GNU system.

@node Compatibility

@node Compatibility

@section Compatibility with Other Implementations

@section Compatibility with Other Implementations

@cindex compatibility with C and @sc{posix} standards

@cindex compatibility with C and @sc{posix} standards

@cindex @sc{posix} compatibility

@cindex @sc{posix} compatibility

With occasional exceptions, utility programs and libraries for GNU

With occasional exceptions, utility programs and libraries for GNU

should be upward compatible with those in Berkeley Unix, and upward

should be upward compatible with those in Berkeley Unix, and upward

compatible with Standard C if Standard C specifies their

compatible with Standard C if Standard C specifies their

behavior, and upward compatible with @sc{posix} if @sc{posix} specifies

behavior, and upward compatible with @sc{posix} if @sc{posix} specifies

their behavior.

their behavior.

When these standards conflict, it is useful to offer compatibility

When these standards conflict, it is useful to offer compatibility

modes for each of them.

modes for each of them.

@cindex options for compatibility

@cindex options for compatibility

Standard C and @sc{posix} prohibit many kinds of extensions.  Feel

Standard C and @sc{posix} prohibit many kinds of extensions.  Feel

free to make the extensions anyway, and include a @samp{--ansi},

free to make the extensions anyway, and include a @samp{--ansi},

@samp{--posix}, or @samp{--compatible} option to turn them off.

@samp{--posix}, or @samp{--compatible} option to turn them off.

However, if the extension has a significant chance of breaking any real

However, if the extension has a significant chance of breaking any real

programs or scripts, then it is not really upward compatible.  So you

programs or scripts, then it is not really upward compatible.  So you

should try to redesign its interface to make it upward compatible.

should try to redesign its interface to make it upward compatible.

@cindex @code{POSIXLY_CORRECT}, environment variable

@cindex @code{POSIXLY_CORRECT}, environment variable

Many GNU programs suppress extensions that conflict with @sc{posix} if the

Many GNU programs suppress extensions that conflict with @sc{posix} if the

environment variable @code{POSIXLY_CORRECT} is defined (even if it is

environment variable @code{POSIXLY_CORRECT} is defined (even if it is

defined with a null value).  Please make your program recognize this

defined with a null value).  Please make your program recognize this

variable if appropriate.

variable if appropriate.

When a feature is used only by users (not by programs or command

When a feature is used only by users (not by programs or command

files), and it is done poorly in Unix, feel free to replace it

files), and it is done poorly in Unix, feel free to replace it

completely with something totally different and better.  (For example,

completely with something totally different and better.  (For example,

@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible

@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible

feature as well.  (There is a free @code{vi} clone, so we offer it.)

feature as well.  (There is a free @code{vi} clone, so we offer it.)

Additional useful features are welcome regardless of whether

Additional useful features are welcome regardless of whether

there is any precedent for them.

there is any precedent for them.

@node Using Extensions

@node Using Extensions

@section Using Non-standard Features

@section Using Non-standard Features

@cindex non-standard extensions

@cindex non-standard extensions

Many GNU facilities that already exist support a number of convenient

Many GNU facilities that already exist support a number of convenient

extensions over the comparable Unix facilities.  Whether to use these

extensions over the comparable Unix facilities.  Whether to use these

extensions in implementing your program is a difficult question.

extensions in implementing your program is a difficult question.

On the one hand, using the extensions can make a cleaner program.

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

On the other hand, people will not be able to build the program

unless the other GNU tools are available.  This might cause the

unless the other GNU tools are available.  This might cause the

program to work on fewer kinds of machines.

program to work on fewer kinds of machines.

With some extensions, it might be easy to provide both alternatives.

With some extensions, it might be easy to provide both alternatives.

For example, you can define functions with a ``keyword'' @code{INLINE}

For example, you can define functions with a ``keyword'' @code{INLINE}

and define that as a macro to expand into either @code{inline} or

and define that as a macro to expand into either @code{inline} or

nothing, depending on the compiler.

nothing, depending on the compiler.

In general, perhaps it is best not to use the extensions if you can

In general, perhaps it is best not to use the extensions if you can

straightforwardly do without them, but to use the extensions if they

straightforwardly do without them, but to use the extensions if they

are a big improvement.

are a big improvement.

An exception to this rule are the large, established programs (such as

An exception to this rule are the large, established programs (such as

Emacs) which run on a great variety of systems.  Using GNU extensions in

Emacs) which run on a great variety of systems.  Using GNU extensions in

such programs would make many users unhappy, so we don't do that.

such programs would make many users unhappy, so we don't do that.

Another exception is for programs that are used as part of compilation:

Another exception is for programs that are used as part of compilation:

anything that must be compiled with other compilers in order to

anything that must be compiled with other compilers in order to

bootstrap the GNU compilation facilities.  If these require the GNU

bootstrap the GNU compilation facilities.  If these require the GNU

compiler, then no one can compile them without having them installed

compiler, then no one can compile them without having them installed

already.  That would be extremely troublesome in certain cases.

already.  That would be extremely troublesome in certain cases.

@node Standard C

@node Standard C

@section Standard C and Pre-Standard C

@section Standard C and Pre-Standard C

@cindex @sc{ansi} C standard

@cindex @sc{ansi} C standard

1989 Standard C is widespread enough now that it is ok to use its

1989 Standard C is widespread enough now that it is ok to use its

features in new programs.  There is one exception: do not ever use the

features in new programs.  There is one exception: do not ever use the

``trigraph'' feature of Standard C.

``trigraph'' feature of Standard C.

1999 Standard C is not widespread yet, so please do not require its

1999 Standard C is not widespread yet, so please do not require its

features in programs.  It is ok to use its features if they are present.

features in programs.  It is ok to use its features if they are present.

However, it is easy to support pre-standard compilers in most programs,

However, it is easy to support pre-standard compilers in most programs,

so if you know how to do that, feel free.  If a program you are

so if you know how to do that, feel free.  If a program you are

maintaining has such support, you should try to keep it working.

maintaining has such support, you should try to keep it working.

@cindex function prototypes

@cindex function prototypes

To support pre-standard C, instead of writing function definitions in

To support pre-standard C, instead of writing function definitions in

standard prototype form,

standard prototype form,

@example

@example

int

int

foo (int x, int y)

foo (int x, int y)

@dots{}

@dots{}

@end example

@end example

@noindent

@noindent

write the definition in pre-standard style like this,

write the definition in pre-standard style like this,

@example

@example

int

int

foo (x, y)

foo (x, y)

     int x, y;

     int x, y;

@dots{}

@dots{}

@end example

@end example

@noindent

@noindent

and use a separate declaration to specify the argument prototype:

and use a separate declaration to specify the argument prototype:

@example

@example

int foo (int, int);

int foo (int, int);

@end example

@end example

You need such a declaration anyway, in a header file, to get the benefit

You need such a declaration anyway, in a header file, to get the benefit

of prototypes in all the files where the function is called.  And once

of prototypes in all the files where the function is called.  And once

you have the declaration, you normally lose nothing by writing the

you have the declaration, you normally lose nothing by writing the

function definition in the pre-standard style.

function definition in the pre-standard style.

This technique does not work for integer types narrower than @code{int}.

This technique does not work for integer types narrower than @code{int}.

If you think of an argument as being of a type narrower than @code{int},

If you think of an argument as being of a type narrower than @code{int},

declare it as @code{int} instead.

declare it as @code{int} instead.

There are a few special cases where this technique is hard to use.  For

There are a few special cases where this technique is hard to use.  For

example, if a function argument needs to hold the system type

example, if a function argument needs to hold the system type

@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than

@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than

@code{int} on some machines; but you cannot use @code{int} instead,

@code{int} on some machines; but you cannot use @code{int} instead,

because @code{dev_t} is wider than @code{int} on some machines.  There

because @code{dev_t} is wider than @code{int} on some machines.  There

is no type you can safely use on all machines in a non-standard

is no type you can safely use on all machines in a non-standard

definition.  The only way to support non-standard C and pass such an

definition.  The only way to support non-standard C and pass such an

argument is to check the width of @code{dev_t} using Autoconf and choose

argument is to check the width of @code{dev_t} using Autoconf and choose

the argument type accordingly.  This may not be worth the trouble.

the argument type accordingly.  This may not be worth the trouble.

In order to support pre-standard compilers that do not recognize

In order to support pre-standard compilers that do not recognize

prototypes, you may want to use a preprocessor macro like this:

prototypes, you may want to use a preprocessor macro like this:

@example

@example

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

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

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

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

#define P_(proto) proto

#define P_(proto) proto

#else

#else

#define P_(proto) ()

#define P_(proto) ()

#endif

#endif

@end example

@end example

@node Conditional Compilation

@node Conditional Compilation

@section Conditional Compilation

@section Conditional Compilation

When supporting configuration options already known when building your

When supporting configuration options already known when building your

program we prefer using @code{if (... )} over conditional compilation,

program we prefer using @code{if (... )} over conditional compilation,

as in the former case the compiler is able to perform more extensive

as in the former case the compiler is able to perform more extensive

checking of all possible code paths.

checking of all possible code paths.

For example, please write

For example, please write

@smallexample

@smallexample

  if (HAS_FOO)

  if (HAS_FOO)

    ...

    ...

  else

  else

    ...

    ...

@end smallexample

@end smallexample

@noindent

@noindent

instead of:

instead of:

@smallexample

@smallexample

  #ifdef HAS_FOO

  #ifdef HAS_FOO

    ...

    ...

  #else

  #else

    ...

    ...

  #endif

  #endif

@end smallexample

@end smallexample

A modern compiler such as GCC will generate exactly the same code in

A modern compiler such as GCC will generate exactly the same code in

both cases, and we have been using similar techniques with good success

both cases, and we have been using similar techniques with good success

in several projects.  Of course, the former method assumes that

in several projects.  Of course, the former method assumes that

@code{HAS_FOO} is defined as either 0 or 1.

@code{HAS_FOO} is defined as either 0 or 1.

While this is not a silver bullet solving all portability problems,

While this is not a silver bullet solving all portability problems,

and is not always appropriate, following this policy would have saved

and is not always appropriate, following this policy would have saved

GCC developers many hours, or even days, per year.

GCC developers many hours, or even days, per year.

In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in

In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in

GCC which cannot be simply used in @code{if( ...)} statements, there is

GCC which cannot be simply used in @code{if( ...)} statements, there is

an easy workaround.  Simply introduce another macro

an easy workaround.  Simply introduce another macro

@code{HAS_REVERSIBLE_CC_MODE} as in the following example:

@code{HAS_REVERSIBLE_CC_MODE} as in the following example:

@smallexample

@smallexample

  #ifdef REVERSIBLE_CC_MODE

  #ifdef REVERSIBLE_CC_MODE

  #define HAS_REVERSIBLE_CC_MODE 1

  #define HAS_REVERSIBLE_CC_MODE 1

  #else

  #else

  #define HAS_REVERSIBLE_CC_MODE 0

  #define HAS_REVERSIBLE_CC_MODE 0

  #endif

  #endif

@end smallexample

@end smallexample

@node Program Behavior

@node Program Behavior

@chapter Program Behavior for All Programs

@chapter Program Behavior for All Programs

This chapter describes conventions for writing robust

This chapter describes conventions for writing robust

software.  It also describes general standards for error messages, the

software.  It also describes general standards for error messages, the

command line interface, and how libraries should behave.

command line interface, and how libraries should behave.

@menu

@menu

* Non-GNU Standards::           We consider standards such as POSIX;

* Non-GNU Standards::           We consider standards such as POSIX;

                                  we don't "obey" them.

                                  we don't "obey" them.

* Semantics::                   Writing robust programs.

* Semantics::                   Writing robust programs.

* Libraries::                   Library behavior.

* Libraries::                   Library behavior.

* Errors::                      Formatting error messages.

* Errors::                      Formatting error messages.

* User Interfaces::             Standards about interfaces generally.

* User Interfaces::             Standards about interfaces generally.

* Graphical Interfaces::        Standards for graphical interfaces.

* Graphical Interfaces::        Standards for graphical interfaces.

* Command-Line Interfaces::     Standards for command line interfaces.

* Command-Line Interfaces::     Standards for command line interfaces.

* Option Table::                Table of long options.

* Option Table::                Table of long options.

* Memory Usage::                When and how to care about memory needs.

* Memory Usage::                When and how to care about memory needs.

* File Usage::                  Which files to use, and where.

* File Usage::                  Which files to use, and where.

@end menu

@end menu

@node Non-GNU Standards

@node Non-GNU Standards

@section Non-GNU Standards

@section Non-GNU Standards

The GNU Project regards standards published by other organizations as

The GNU Project regards standards published by other organizations as

suggestions, not orders.  We consider those standards, but we do not

suggestions, not orders.  We consider those standards, but we do not

``obey'' them.  In developing a GNU program, you should implement

``obey'' them.  In developing a GNU program, you should implement

an outside standard's specifications when that makes the GNU system

an outside standard's specifications when that makes the GNU system

better overall in an objective sense.  When it doesn't, you shouldn't.

better overall in an objective sense.  When it doesn't, you shouldn't.

In most cases, following published standards is convenient for

In most cases, following published standards is convenient for

users---it means that their programs or scripts will work more

users---it means that their programs or scripts will work more

portably.  For instance, GCC implements nearly all the features of

portably.  For instance, GCC implements nearly all the features of

Standard C as specified by that standard.  C program developers would

Standard C as specified by that standard.  C program developers would

be unhappy if it did not.  And GNU utilities mostly follow

be unhappy if it did not.  And GNU utilities mostly follow

specifications of POSIX.2; shell script writers and users would be

specifications of POSIX.2; shell script writers and users would be

unhappy if our programs were incompatible.

unhappy if our programs were incompatible.

But we do not follow either of these specifications rigidly, and there

But we do not follow either of these specifications rigidly, and there

are specific points on which we decided not to follow them, so as to

are specific points on which we decided not to follow them, so as to

make the GNU system better for users.

make the GNU system better for users.

For instance, Standard C says that nearly all extensions to C are

For instance, Standard C says that nearly all extensions to C are

prohibited.  How silly!  GCC implements many extensions, some of which

prohibited.  How silly!  GCC implements many extensions, some of which

were later adopted as part of the standard.  If you want these

were later adopted as part of the standard.  If you want these

constructs to give an error message as ``required'' by the standard,

constructs to give an error message as ``required'' by the standard,

you must specify @samp{--pedantic}, which was implemented only so that

you must specify @samp{--pedantic}, which was implemented only so that

we can say ``GCC is a 100% implementation of the standard,'' not

we can say ``GCC is a 100% implementation of the standard,'' not

because there is any reason to actually use it.

because there is any reason to actually use it.

POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by

POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by

default in units of 512 bytes.  What users want is units of 1k, so

default in units of 512 bytes.  What users want is units of 1k, so

that is what we do by default.  If you want the ridiculous behavior

that is what we do by default.  If you want the ridiculous behavior

``required'' by POSIX, you must set the environment variable

``required'' by POSIX, you must set the environment variable

@samp{POSIXLY_CORRECT} (which was originally going to be named

@samp{POSIXLY_CORRECT} (which was originally going to be named

@samp{POSIX_ME_HARDER}).

@samp{POSIX_ME_HARDER}).

GNU utilities also depart from the letter of the POSIX.2 specification

GNU utilities also depart from the letter of the POSIX.2 specification

when they support long-named command-line options, and intermixing

when they support long-named command-line options, and intermixing

options with ordinary arguments.  This minor incompatibility with

options with ordinary arguments.  This minor incompatibility with

POSIX is never a problem in practice, and it is very useful.

POSIX is never a problem in practice, and it is very useful.

In particular, don't reject a new feature, or remove an old one,

In particular, don't reject a new feature, or remove an old one,

merely because a standard says it is ``forbidden'' or ``deprecated.''

merely because a standard says it is ``forbidden'' or ``deprecated.''

@node Semantics

@node Semantics

@section Writing Robust Programs

@section Writing Robust Programs

@cindex arbitrary limits on data

@cindex arbitrary limits on data

Avoid arbitrary limits on the length or number of @emph{any} data

Avoid arbitrary limits on the length or number of @emph{any} data

structure, including file names, lines, files, and symbols, by allocating

structure, including file names, lines, files, and symbols, by allocating

all data structures dynamically.  In most Unix utilities, ``long lines

all data structures dynamically.  In most Unix utilities, ``long lines

are silently truncated''.  This is not acceptable in a GNU utility.

are silently truncated''.  This is not acceptable in a GNU utility.

@cindex @code{NUL} characters

@cindex @code{NUL} characters

Utilities reading files should not drop NUL characters, or any other

Utilities reading files should not drop NUL characters, or any other

nonprinting characters @emph{including those with codes above 0177}.

nonprinting characters @emph{including those with codes above 0177}.

The only sensible exceptions would be utilities specifically intended

The only sensible exceptions would be utilities specifically intended

for interface to certain types of terminals or printers

for interface to certain types of terminals or printers

that can't handle those characters.

that can't handle those characters.

Whenever possible, try to make programs work properly with

Whenever possible, try to make programs work properly with

sequences of bytes that represent multibyte characters, using encodings

sequences of bytes that represent multibyte characters, using encodings

such as UTF-8 and others.

such as UTF-8 and others.

@cindex error messages

@cindex error messages

Check every system call for an error return, unless you know you wish to

Check every system call for an error return, unless you know you wish to

ignore errors.  Include the system error text (from @code{perror} or

ignore errors.  Include the system error text (from @code{perror} or

equivalent) in @emph{every} error message resulting from a failing

equivalent) in @emph{every} error message resulting from a failing

system call, as well as the name of the file if any and the name of the

system call, as well as the name of the file if any and the name of the

utility.  Just ``cannot open foo.c'' or ``stat failed'' is not

utility.  Just ``cannot open foo.c'' or ``stat failed'' is not

sufficient.

sufficient.

@cindex @code{malloc} return value

@cindex @code{malloc} return value

@cindex memory allocation failure

@cindex memory allocation failure

Check every call to @code{malloc} or @code{realloc} to see if it

Check every call to @code{malloc} or @code{realloc} to see if it

returned zero.  Check @code{realloc} even if you are making the block

returned zero.  Check @code{realloc} even if you are making the block

smaller; in a system that rounds block sizes to a power of 2,

smaller; in a system that rounds block sizes to a power of 2,

@code{realloc} may get a different block if you ask for less space.

@code{realloc} may get a different block if you ask for less space.

In Unix, @code{realloc} can destroy the storage block if it returns

In Unix, @code{realloc} can destroy the storage block if it returns

zero.  GNU @code{realloc} does not have this bug: if it fails, the

zero.  GNU @code{realloc} does not have this bug: if it fails, the

original block is unchanged.  Feel free to assume the bug is fixed.  If

original block is unchanged.  Feel free to assume the bug is fixed.  If

you wish to run your program on Unix, and wish to avoid lossage in this

you wish to run your program on Unix, and wish to avoid lossage in this

case, you can use the GNU @code{malloc}.

case, you can use the GNU @code{malloc}.

You must expect @code{free} to alter the contents of the block that was

You must expect @code{free} to alter the contents of the block that was

freed.  Anything you want to fetch from the block, you must fetch before

freed.  Anything you want to fetch from the block, you must fetch before

calling @code{free}.

calling @code{free}.

If @code{malloc} fails in a noninteractive program, make that a fatal

If @code{malloc} fails in a noninteractive program, make that a fatal

error.  In an interactive program (one that reads commands from the

error.  In an interactive program (one that reads commands from the

user), it is better to abort the command and return to the command

user), it is better to abort the command and return to the command

reader loop.  This allows the user to kill other processes to free up

reader loop.  This allows the user to kill other processes to free up

virtual memory, and then try the command again.

virtual memory, and then try the command again.

@cindex command-line arguments, decoding

@cindex command-line arguments, decoding

Use @code{getopt_long} to decode arguments, unless the argument syntax

Use @code{getopt_long} to decode arguments, unless the argument syntax

makes this unreasonable.

makes this unreasonable.

When static storage is to be written in during program execution, use

When static storage is to be written in during program execution, use

explicit C code to initialize it.  Reserve C initialized declarations

explicit C code to initialize it.  Reserve C initialized declarations

for data that will not be changed.

for data that will not be changed.

@c ADR: why?

@c ADR: why?

Try to avoid low-level interfaces to obscure Unix data structures (such

Try to avoid low-level interfaces to obscure Unix data structures (such

as file directories, utmp, or the layout of kernel memory), since these

as file directories, utmp, or the layout of kernel memory), since these

are less likely to work compatibly.  If you need to find all the files

are less likely to work compatibly.  If you need to find all the files

in a directory, use @code{readdir} or some other high-level interface.

in a directory, use @code{readdir} or some other high-level interface.

These are supported compatibly by GNU.

These are supported compatibly by GNU.

@cindex signal handling

@cindex signal handling

The preferred signal handling facilities are the BSD variant of

The preferred signal handling facilities are the BSD variant of

@code{signal}, and the @sc{posix} @code{sigaction} function; the

@code{signal}, and the @sc{posix} @code{sigaction} function; the

alternative USG @code{signal} interface is an inferior design.

alternative USG @code{signal} interface is an inferior design.

Nowadays, using the @sc{posix} signal functions may be the easiest way

Nowadays, using the @sc{posix} signal functions may be the easiest way

to make a program portable.  If you use @code{signal}, then on GNU/Linux

to make a program portable.  If you use @code{signal}, then on GNU/Linux

systems running GNU libc version 1, you should include

systems running GNU libc version 1, you should include

@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD

@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD

behavior.  It is up to you whether to support systems where

behavior.  It is up to you whether to support systems where

@code{signal} has only the USG behavior, or give up on them.

@code{signal} has only the USG behavior, or give up on them.

@cindex impossible conditions

@cindex impossible conditions

In error checks that detect ``impossible'' conditions, just abort.

In error checks that detect ``impossible'' conditions, just abort.

There is usually no point in printing any message.  These checks

There is usually no point in printing any message.  These checks

indicate the existence of bugs.  Whoever wants to fix the bugs will have

indicate the existence of bugs.  Whoever wants to fix the bugs will have

to read the source code and run a debugger.  So explain the problem with

to read the source code and run a debugger.  So explain the problem with

comments in the source.  The relevant data will be in variables, which

comments in the source.  The relevant data will be in variables, which

are easy to examine with the debugger, so there is no point moving them

are easy to examine with the debugger, so there is no point moving them

elsewhere.

elsewhere.

Do not use a count of errors as the exit status for a program.

Do not use a count of errors as the exit status for a program.

@emph{That does not work}, because exit status values are limited to 8

@emph{That does not work}, because exit status values are limited to 8

bits (0 through 255).  A single run of the program might have 256

bits (0 through 255).  A single run of the program might have 256

errors; if you try to return 256 as the exit status, the parent process

errors; if you try to return 256 as the exit status, the parent process

will see 0 as the status, and it will appear that the program succeeded.

will see 0 as the status, and it will appear that the program succeeded.

@cindex temporary files

@cindex temporary files

@cindex @code{TMPDIR} environment variable

@cindex @code{TMPDIR} environment variable

If you make temporary files, check the @code{TMPDIR} environment

If you make temporary files, check the @code{TMPDIR} environment

variable; if that variable is defined, use the specified directory

variable; if that variable is defined, use the specified directory

instead of @file{/tmp}.

instead of @file{/tmp}.

In addition, be aware that there is a possible security problem when

In addition, be aware that there is a possible security problem when

creating temporary files in world-writable directories.  In C, you can

creating temporary files in world-writable directories.  In C, you can

avoid this problem by creating temporary files in this manner:

avoid this problem by creating temporary files in this manner:

@example

@example

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

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

@end example

@end example

@noindent

@noindent

or by using the @code{mkstemps} function from libiberty.

or by using the @code{mkstemps} function from libiberty.

In bash, use @code{set -C} to avoid this problem.

In bash, use @code{set -C} to avoid this problem.

@node Libraries

@node Libraries

@section Library Behavior

@section Library Behavior

@cindex libraries

@cindex libraries

Try to make library functions reentrant.  If they need to do dynamic

Try to make library functions reentrant.  If they need to do dynamic

storage allocation, at least try to avoid any nonreentrancy aside from

storage allocation, at least try to avoid any nonreentrancy aside from

that of @code{malloc} itself.

that of @code{malloc} itself.

Here are certain name conventions for libraries, to avoid name

Here are certain name conventions for libraries, to avoid name

conflicts.

conflicts.

Choose a name prefix for the library, more than two characters long.

Choose a name prefix for the library, more than two characters long.

All external function and variable names should start with this

All external function and variable names should start with this

prefix.  In addition, there should only be one of these in any given

prefix.  In addition, there should only be one of these in any given

library member.  This usually means putting each one in a separate

library member.  This usually means putting each one in a separate

source file.

source file.

An exception can be made when two external symbols are always used

An exception can be made when two external symbols are always used

together, so that no reasonable program could use one without the

together, so that no reasonable program could use one without the

other; then they can both go in the same file.

other; then they can both go in the same file.

External symbols that are not documented entry points for the user

External symbols that are not documented entry points for the user

should have names beginning with @samp{_}.  The @samp{_} should be

should have names beginning with @samp{_}.  The @samp{_} should be

followed by the chosen name prefix for the library, to prevent

followed by the chosen name prefix for the library, to prevent

collisions with other libraries.  These can go in the same files with

collisions with other libraries.  These can go in the same files with

user entry points if you like.

user entry points if you like.

Static functions and variables can be used as you like and need not

Static functions and variables can be used as you like and need not

fit any naming convention.

fit any naming convention.

@node Errors

@node Errors

@section Formatting Error Messages

@section Formatting Error Messages

@cindex formatting error messages

@cindex formatting error messages

@cindex error messages, formatting

@cindex error messages, formatting

Error messages from compilers should look like this:

Error messages from compilers should look like this:

@example

@example

@var{source-file-name}:@var{lineno}: @var{message}

@var{source-file-name}:@var{lineno}: @var{message}

@end example

@end example

@noindent

@noindent

If you want to mention the column number, use one of these formats:

If you want to mention the column number, use one of these formats:

@example

@example

@var{source-file-name}:@var{lineno}:@var{column}: @var{message}

@var{source-file-name}:@var{lineno}:@var{column}: @var{message}

@var{source-file-name}:@var{lineno}.@var{column}: @var{message}

@var{source-file-name}:@var{lineno}.@var{column}: @var{message}

@end example

@end example

@noindent

@noindent

Line numbers should start from 1 at the beginning of the file, and

Line numbers should start from 1 at the beginning of the file, and

column numbers should start from 1 at the beginning of the line.  (Both

column numbers should start from 1 at the beginning of the line.  (Both

of these conventions are chosen for compatibility.)  Calculate column

of these conventions are chosen for compatibility.)  Calculate column

numbers assuming that space and all ASCII printing characters have

numbers assuming that space and all ASCII printing characters have

equal width, and assuming tab stops every 8 columns.

equal width, and assuming tab stops every 8 columns.

The error message can also give both the starting and ending positions

The error message can also give both the starting and ending positions

of the erroneous text.  There are several formats so that you can

of the erroneous text.  There are several formats so that you can

avoid redundant information such as a duplicate line number.

avoid redundant information such as a duplicate line number.

Here are the possible formats:

Here are the possible formats:

@example

@example

@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}

@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}

@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}

@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}

@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}

@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}

@end example

@end example

@noindent

@noindent

When an error is spread over several files, you can use this format:

When an error is spread over several files, you can use this format:

@example

@example

@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}

@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}

@end example

@end example

Error messages from other noninteractive programs should look like this:

Error messages from other noninteractive programs should look like this:

@example

@example

@var{program}:@var{source-file-name}:@var{lineno}: @var{message}

@var{program}:@var{source-file-name}:@var{lineno}: @var{message}

@end example

@end example

@noindent

@noindent

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

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

@example

@example

@var{program}: @var{message}

@var{program}: @var{message}

@end example

@end example

@noindent

@noindent

when there is no relevant source file.

when there is no relevant source file.

If you want to mention the column number, use this format:

If you want to mention the column number, use this format:

@example

@example

@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}

@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}

@end example

@end example

In an interactive program (one that is reading commands from a

In an interactive program (one that is reading commands from a

terminal), it is better not to include the program name in an error

terminal), it is better not to include the program name in an error

message.  The place to indicate which program is running is in the

message.  The place to indicate which program is running is in the

prompt or with the screen layout.  (When the same program runs with

prompt or with the screen layout.  (When the same program runs with

input from a source other than a terminal, it is not interactive and

input from a source other than a terminal, it is not interactive and

would do best to print error messages using the noninteractive style.)

would do best to print error messages using the noninteractive style.)

The string @var{message} should not begin with a capital letter when

The string @var{message} should not begin with a capital letter when

it follows a program name and/or file name, because that isn't the

it follows a program name and/or file name, because that isn't the

beginning of a sentence.  (The sentence conceptually starts at the

beginning of a sentence.  (The sentence conceptually starts at the

beginning of the line.)  Also, it should not end with a period.

beginning of the line.)  Also, it should not end with a period.

Error messages from interactive programs, and other messages such as

Error messages from interactive programs, and other messages such as

usage messages, should start with a capital letter.  But they should not

usage messages, should start with a capital letter.  But they should not

end with a period.

end with a period.

@node User Interfaces

@node User Interfaces

@section Standards for Interfaces Generally

@section Standards for Interfaces Generally

@cindex program name and its behavior

@cindex program name and its behavior

@cindex behavior, dependent on program's name

@cindex behavior, dependent on program's name

Please don't make the behavior of a utility depend on the name used

Please don't make the behavior of a utility depend on the name used

to invoke it.  It is useful sometimes to make a link to a utility

to invoke it.  It is useful sometimes to make a link to a utility

with a different name, and that should not change what it does.

with a different name, and that should not change what it does.

Instead, use a run time option or a compilation switch or both

Instead, use a run time option or a compilation switch or both

to select among the alternate behaviors.

to select among the alternate behaviors.

@cindex output device and program's behavior

@cindex output device and program's behavior

Likewise, please don't make the behavior of the program depend on the

Likewise, please don't make the behavior of the program depend on the

type of output device it is used with.  Device independence is an

type of output device it is used with.  Device independence is an

important principle of the system's design; do not compromise it merely

important principle of the system's design; do not compromise it merely

to save someone from typing an option now and then.  (Variation in error

to save someone from typing an option now and then.  (Variation in error

message syntax when using a terminal is ok, because that is a side issue

message syntax when using a terminal is ok, because that is a side issue

that people do not depend on.)

that people do not depend on.)

If you think one behavior is most useful when the output is to a

If you think one behavior is most useful when the output is to a

terminal, and another is most useful when the output is a file or a

terminal, and another is most useful when the output is a file or a

pipe, then it is usually best to make the default behavior the one that

pipe, then it is usually best to make the default behavior the one that

is useful with output to a terminal, and have an option for the other

is useful with output to a terminal, and have an option for the other

behavior.

behavior.

Compatibility requires certain programs to depend on the type of output

Compatibility requires certain programs to depend on the type of output

device.  It would be disastrous if @code{ls} or @code{sh} did not do so

device.  It would be disastrous if @code{ls} or @code{sh} did not do so

in the way all users expect.  In some of these cases, we supplement the

in the way all users expect.  In some of these cases, we supplement the

program with a preferred alternate version that does not depend on the

program with a preferred alternate version that does not depend on the

output device type.  For example, we provide a @code{dir} program much

output device type.  For example, we provide a @code{dir} program much

like @code{ls} except that its default output format is always

like @code{ls} except that its default output format is always

multi-column format.

multi-column format.

@node Graphical Interfaces

@node Graphical Interfaces

@section Standards for Graphical Interfaces

@section Standards for Graphical Interfaces

@cindex graphical user interface

@cindex graphical user interface

@cindex gtk+

@cindex gtk+

When you write a program that provides a graphical user interface,

When you write a program that provides a graphical user interface,

please make it work with X Windows and the GTK+ toolkit unless the

please make it work with X Windows and the GTK+ toolkit unless the

functionality specifically requires some alternative (for example,

functionality specifically requires some alternative (for example,

``displaying jpeg images while in console mode'').

``displaying jpeg images while in console mode'').

In addition, please provide a command-line interface to control the

In addition, please provide a command-line interface to control the

functionality.  (In many cases, the graphical user interface can be a

functionality.  (In many cases, the graphical user interface can be a

separate program which invokes the command-line program.)  This is

separate program which invokes the command-line program.)  This is

so that the same jobs can be done from scripts.

so that the same jobs can be done from scripts.

@cindex corba

@cindex corba

@cindex gnome

@cindex gnome

Please also consider providing a CORBA interface (for use from GNOME), a

Please also consider providing a CORBA interface (for use from GNOME), a

library interface (for use from C), and perhaps a keyboard-driven

library interface (for use from C), and perhaps a keyboard-driven

console interface (for use by users from console mode).  Once you are

console interface (for use by users from console mode).  Once you are

doing the work to provide the functionality and the graphical interface,

doing the work to provide the functionality and the graphical interface,

these won't be much extra work.

these won't be much extra work.

@node Command-Line Interfaces

@node Command-Line Interfaces

@section Standards for Command Line Interfaces

@section Standards for Command Line Interfaces

@cindex command-line interface

@cindex command-line interface

@findex getopt

@findex getopt

It is a good idea to follow the @sc{posix} guidelines for the

It is a good idea to follow the @sc{posix} guidelines for the

command-line options of a program.  The easiest way to do this is to use

command-line options of a program.  The easiest way to do this is to use

@code{getopt} to parse them.  Note that the GNU version of @code{getopt}

@code{getopt} to parse them.  Note that the GNU version of @code{getopt}

will normally permit options anywhere among the arguments unless the

will normally permit options anywhere among the arguments unless the

special argument @samp{--} is used.  This is not what @sc{posix}

special argument @samp{--} is used.  This is not what @sc{posix}

specifies; it is a GNU extension.

specifies; it is a GNU extension.

@cindex long-named options

@cindex long-named options

Please define long-named options that are equivalent to the

Please define long-named options that are equivalent to the

single-letter Unix-style options.  We hope to make GNU more user

single-letter Unix-style options.  We hope to make GNU more user

friendly this way.  This is easy to do with the GNU function

friendly this way.  This is easy to do with the GNU function

@code{getopt_long}.

@code{getopt_long}.

One of the advantages of long-named options is that they can be

One of the advantages of long-named options is that they can be

consistent from program to program.  For example, users should be able

consistent from program to program.  For example, users should be able

to expect the ``verbose'' option of any GNU program which has one, to be

to expect the ``verbose'' option of any GNU program which has one, to be

spelled precisely @samp{--verbose}.  To achieve this uniformity, look at

spelled precisely @samp{--verbose}.  To achieve this uniformity, look at

the table of common long-option names when you choose the option names

the table of common long-option names when you choose the option names

for your program (@pxref{Option Table}).

for your program (@pxref{Option Table}).

It is usually a good idea for file names given as ordinary arguments to

It is usually a good idea for file names given as ordinary arguments to

be input files only; any output files would be specified using options

be input files only; any output files would be specified using options

(preferably @samp{-o} or @samp{--output}).  Even if you allow an output

(preferably @samp{-o} or @samp{--output}).  Even if you allow an output

file name as an ordinary argument for compatibility, try to provide an

file name as an ordinary argument for compatibility, try to provide an

option as another way to specify it.  This will lead to more consistency

option as another way to specify it.  This will lead to more consistency

among GNU utilities, and fewer idiosyncrasies for users to remember.

among GNU utilities, and fewer idiosyncrasies for users to remember.

@cindex standard command-line options

@cindex standard command-line options

@cindex options, standard command-line

@cindex options, standard command-line

@cindex CGI programs, standard options for

@cindex CGI programs, standard options for

@cindex PATH_INFO, specifying standard options as

@cindex PATH_INFO, specifying standard options as

All programs should support two standard options: @samp{--version}

All programs should support two standard options: @samp{--version}

and @samp{--help}.  CGI programs should accept these as command-line

and @samp{--help}.  CGI programs should accept these as command-line

options, and also if given as the @env{PATH_INFO}; for instance,

options, and also if given as the @env{PATH_INFO}; for instance,

visiting @url{http://example.org/p.cgi/--help} in a browser should

visiting @url{http://example.org/p.cgi/--help} in a browser should

output the same information as invoking @samp{p.cgi --help} from the

output the same information as invoking @samp{p.cgi --help} from the

command line.

command line.

@menu

@menu

* --version::       The standard output for --version.

* --version::       The standard output for --version.

* --help::          The standard output for --help.

* --help::          The standard output for --help.

@end menu

@end menu

@node --version

@node --version

@subsection @option{--version}

@subsection @option{--version}

@cindex @samp{--version} output

@cindex @samp{--version} output

The standard @code{--version} option should direct the program to

The standard @code{--version} option should direct the program to

print information about its name, version, origin and legal status,

print information about its name, version, origin and legal status,

all on standard output, and then exit successfully.  Other options and

all on standard output, and then exit successfully.  Other options and

arguments should be ignored once this is seen, and the program should

arguments should be ignored once this is seen, and the program should

not perform its normal function.

not perform its normal function.

@cindex canonical name of a program

@cindex canonical name of a program

@cindex program's canonical name

@cindex program's canonical name

The first line is meant to be easy for a program to parse; the version

The first line is meant to be easy for a program to parse; the version

number proper starts after the last space.  In addition, it contains

number proper starts after the last space.  In addition, it contains

the canonical name for this program, in this format:

the canonical name for this program, in this format:

@example

@example

GNU Emacs 19.30

GNU Emacs 19.30

@end example

@end example

@noindent

@noindent

The program's name should be a constant string; @emph{don't} compute it

The program's name should be a constant string; @emph{don't} compute it

from @code{argv[0]}.  The idea is to state the standard or canonical

from @code{argv[0]}.  The idea is to state the standard or canonical

name for the program, not its file name.  There are other ways to find

name for the program, not its file name.  There are other ways to find

out the precise file name where a command is found in @code{PATH}.

out the precise file name where a command is found in @code{PATH}.

If the program is a subsidiary part of a larger package, mention the

If the program is a subsidiary part of a larger package, mention the

package name in parentheses, like this:

package name in parentheses, like this:

@example

@example