Subversion Repositories openrisc_2011-10-31

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

@c %**start of header

@setfilename standards.info

@settitle GNU Coding Standards

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

@set lastupdate April 12, 2010

@c %**end of header

@dircategory GNU organization

@direntry

* Standards: (standards).       GNU coding standards.

@end direntry

@c @setchapternewpage odd

@setchapternewpage off

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

@syncodeindex fn cp

@syncodeindex ky cp

@syncodeindex pg cp

@syncodeindex vr cp

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

@set CODESTD  1

@copying

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

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

2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software

Foundation, Inc.

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

under the terms of the GNU Free Documentation License, Version 1.3 or

any later version published by the Free Software Foundation; with no

Invariant Sections, with no Front-Cover Texts, and with no Back-Cover

Texts.  A copy of the license is included in the section entitled

``GNU Free Documentation License''.

@end copying

@titlepage

@title GNU Coding Standards

@author Richard Stallman, et al.

@author last updated @value{lastupdate}

@page

@vskip 0pt plus 1filll

@insertcopying

@end titlepage

@contents

@ifnottex

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

@top Version

@insertcopying

@end ifnottex

@menu

* Preface::                     About the GNU Coding Standards.

* Legal Issues::                Keeping free software free.

* Design Advice::               General program design.

* Program Behavior::            Program behavior for all programs

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

* Documentation::               Documenting programs.

* Managing Releases::           The release process.

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

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

* Index::

@end menu

@node Preface

@chapter 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 focuses on

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

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

state reasons for writing in a certain way.

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

@cindex downloading this manual

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

Coding Standards from the GNU web server in many

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

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

If you are maintaining an official GNU package, in addition to this

document, please read and follow the GNU maintainer information

(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU

Software}).

@cindex @code{gnustandards-commit@@gnu.org} mailing list

If you want to receive diffs for every change to these GNU documents,

join the mailing list @code{gnustandards-commit@@gnu.org}, via the web

interface at

@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.

Archives are also available there.

@cindex @code{bug-standards@@gnu.org} email address

@cindex Savannah repository for gnustandards

@cindex gnustandards project repository

Please send corrections or suggestions for this document to

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

include a suggested new wording for it, to help us consider the

suggestion efficiently.  We prefer a context diff to the Texinfo

source, but if that's difficult for you, you can make a context diff

for some other version of this document, or propose it in any way that

makes it clear.  The source repository for this document can be found

at @url{http://savannah.gnu.org/projects/gnustandards}.

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

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

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

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

do suggest them.

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

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

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

more maintainable by others.

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

coding standards for a trivial program.

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

This release of the GNU Coding Standards was last updated

@value{lastupdate}.

@node Legal Issues

@chapter Keeping Free Software Free

@cindex legal aspects

This chapter discusses how you can make sure that GNU software

avoids legal difficulties, and other related issues.

@menu

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

* Contributions::               Accepting contributions.

* Trademarks::                  How we deal with trademark issues.

@end menu

@node Reading Non-Free Code

@section Referring to Proprietary Programs

@cindex proprietary programs

@cindex avoiding proprietary code

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

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

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

do try to organize the imitation internally along different lines,

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

irrelevant and dissimilar to your results.

For example, Unix utilities were generally optimized to minimize

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

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

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

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

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

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

adequate.

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

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

dynamic allocation instead.  Make sure your program handles NULs and

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

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

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

Or use a simple garbage collector instead of tracking precisely when

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

@node Contributions

@section Accepting Contributions

@cindex legal papers

@cindex accepting contributions

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

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

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

enough.

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

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

contribution.

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

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

need legal papers for that change.

This also applies to comments and documentation files.  For copyright

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

text, so we need legal papers for all kinds.

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

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

You might have to take that code out again!

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

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

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

get papers.

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

result.

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

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

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

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

@node Trademarks

@section Trademarks

@cindex trademarks

Please do not include any trademark acknowledgements in GNU software

packages or documentation.

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

idea of trademarks, but these acknowledgements feel like kowtowing,

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

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

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

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

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

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

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

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

GNU software or documentation.  In hacker terminology, calling

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

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

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

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

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

@node Design Advice

@chapter General Program Design

@cindex program design

This chapter discusses some of the issues you should take into

account when designing your program.

@c                         Standard or ANSI C

@c

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

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

@c International Standards Organization ISO  adopted the ANSI C 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 A major revision of the C Standard appeared in 1999.

@menu

* Source Language::             Which languages to use.

* Compatibility::               Compatibility with other implementations.

* Using Extensions::            Using non-standard features.

* Standard C::                  Using standard C features.

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

@end menu

@node Source Language

@section Which Languages to Use

@cindex programming languages

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

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

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

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

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

program if 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:

@itemize @bullet

@item

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

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

language anyway.

@item

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

other people, so you may as well please yourself.

@end itemize

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

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

technique.

@cindex Guile

@cindex GNOME and Guile

The standard extensibility interpreter for GNU software is Guile

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

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

Guile also includes bindings for GTK+/GNOME, making it practical to

write modern GUI functionality within Guile.  We don't reject programs

written in other ``scripting languages'' such as Perl and Python, but

using Guile is very important for the overall consistency of the GNU

system.

@node Compatibility

@section Compatibility with Other Implementations

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

@cindex @sc{posix} compatibility

With occasional exceptions, utility programs and libraries for GNU

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

compatible with Standard C if Standard C specifies their

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

their behavior.

When these standards conflict, it is useful to offer compatibility

modes for each of them.

@cindex options for compatibility

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

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

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

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

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

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

@cindex @code{POSIXLY_CORRECT}, environment variable

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

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

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

variable if appropriate.

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

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

@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.)

Additional useful features are welcome regardless of whether

there is any precedent for them.

@node Using Extensions

@section Using Non-standard Features

@cindex non-standard extensions

Many GNU facilities that already exist support a number of convenient

extensions over the comparable Unix facilities.  Whether to use these

extensions in implementing your program is a difficult 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.  This might cause the

program to work on fewer kinds of machines.

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

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

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

nothing, depending on the compiler.

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

are a big improvement.

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

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:

anything that must be compiled with other compilers in order to

bootstrap the GNU compilation facilities.  If these require the GNU

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

already.  That would be extremely troublesome in certain cases.

@node Standard C

@section Standard C and Pre-Standard C

@cindex @sc{ansi} C standard

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

``trigraph'' feature of Standard C.

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.

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

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

@cindex function prototypes

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

standard prototype form,

@example

int

foo (int x, int y)

@dots{}

@end example

@noindent

write the definition in pre-standard style like this,

@example

int

foo (x, y)

     int x, y;

@dots{}

@end example

@noindent

and use a separate declaration to specify the argument prototype:

@example

int foo (int, int);

@end example

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

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

function definition in the pre-standard style.

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},

declare it as @code{int} instead.

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

@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,

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

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

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

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

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

@example

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

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

#define P_(proto) proto

#else

#define P_(proto) ()

#endif

@end example

@node Conditional Compilation

@section Conditional Compilation

When supporting configuration options already known when building your

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

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

checking of all possible code paths.

For example, please write

@smallexample

  if (HAS_FOO)

    ...

  else

    ...

@end smallexample

@noindent

instead of:

@smallexample

  #ifdef HAS_FOO

    ...

  #else

    ...

  #endif

@end smallexample

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

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

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

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

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

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

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

an easy workaround.  Simply introduce another macro

@code{HAS_REVERSIBLE_CC_MODE} as in the following example:

@smallexample

  #ifdef REVERSIBLE_CC_MODE

  #define HAS_REVERSIBLE_CC_MODE 1

  #else

  #define HAS_REVERSIBLE_CC_MODE 0

  #endif

@end smallexample

@node Program Behavior

@chapter Program Behavior for All Programs

This chapter describes conventions for writing robust

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

command line interface, and how libraries should behave.

@menu

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

                                  we don't "obey" them.

* Semantics::                   Writing robust programs.

* Libraries::                   Library behavior.

* Errors::                      Formatting error messages.

* User Interfaces::             Standards about interfaces generally.

* Graphical Interfaces::        Standards for graphical interfaces.

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

* Option Table::                Table of long options.

* OID Allocations::             Table of OID slots for GNU.

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

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

@end menu

@node Non-GNU Standards

@section Non-GNU Standards

The GNU Project regards standards published by other organizations as

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

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

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

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

In most cases, following published standards is convenient for

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

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

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

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

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

unhappy if our programs were incompatible.

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

make the GNU system better for users.

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

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

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

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

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

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

because there is any reason to actually use it.

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

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

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

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

@samp{POSIX_ME_HARDER}).

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

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

options with ordinary arguments.  This minor incompatibility with

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,

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

@node Semantics

@section Writing Robust Programs

@cindex arbitrary limits on data

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

structure, including file names, lines, files, 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.

@cindex @code{NUL} characters

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

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

The only sensible exceptions would be utilities specifically intended

for interface to certain types of terminals or printers

that can't handle those characters.

Whenever possible, try to make programs work properly with

sequences of bytes that represent multibyte characters, using encodings

such as UTF-8 and others.

@cindex error messages

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

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

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

sufficient.

@cindex @code{malloc} return value

@cindex memory allocation failure

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

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.

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

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

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

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

calling @code{free}.

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

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

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

virtual memory, and then try the command again.

@cindex command-line arguments, decoding

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

makes this unreasonable.

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

explicit C code to initialize it.  Reserve C initialized declarations

for data that will not be changed.

@c ADR: why?

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

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

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

These are supported compatibly by GNU.

@cindex signal handling

The preferred signal handling facilities are the BSD variant of

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

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

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

systems running GNU libc version 1, you should include

@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

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

@cindex impossible conditions

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

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

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

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

elsewhere.

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

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

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

@cindex temporary files

@cindex @code{TMPDIR} environment variable

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

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

instead of @file{/tmp}.

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

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

avoid this problem by creating temporary files in this manner:

@example

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

@end example

@noindent

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

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

@node Libraries

@section Library Behavior

@cindex libraries

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

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

that of @code{malloc} itself.

Here are certain name conventions for libraries, to avoid name

conflicts.

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

All external function and variable names should start with this

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

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

source file.

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

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

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

External symbols that are not documented entry points for the user

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

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

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

user entry points if you like.

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

fit any naming convention.

@node Errors

@section Formatting Error Messages

@cindex formatting error messages

@cindex error messages, formatting

Error messages from compilers should look like this:

@example

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

@end example

@noindent

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

@example

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

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

@end example

@noindent

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

of these conventions are chosen for compatibility.)  Calculate column

numbers assuming that space and all ASCII printing characters have

equal width, and assuming tab stops every 8 columns.

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

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

avoid redundant information such as a duplicate line number.

Here are the possible formats:

@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{column-2}: @var{message}

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

@end example

@noindent

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

@example

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

@end example

Error messages from other noninteractive programs should look like this:

@example

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

@end example

@noindent

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

@example

@var{program}: @var{message}

@end example

@noindent

when there is no relevant source file.

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

@example

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

@end example

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

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

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

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

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

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

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

Error messages from interactive programs, and other messages such as

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

end with a period.

@node User Interfaces

@section Standards for Interfaces Generally

@cindex program name and its behavior

@cindex behavior, dependent on program's name

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

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

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

to select among the alternate behaviors.

@cindex output device and program's behavior

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

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

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

that people do not depend on.)

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

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

behavior.

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

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

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

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

multi-column format.

@node Graphical Interfaces

@section Standards for Graphical Interfaces

@cindex graphical user interface

@cindex interface styles

@cindex user interface styles

@cindex GTK+

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

please make it work with the X Window System and the GTK+ toolkit

unless the functionality specifically requires some alternative (for

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

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

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

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

so that the same jobs can be done from scripts.

@cindex CORBA

@cindex GNOME

@cindex D-bus

@cindex keyboard interface

@cindex library interface

Please also consider providing a D-bus interface for use from other

running programs, such as within GNOME.  (GNOME used to use CORBA

for this, but that is being phased out.)  In addition, consider

providing a library interface (for use from C), and perhaps a

keyboard-driven console interface (for use by users from console

mode).  Once you are doing the work to provide the functionality and

the graphical interface, these won't be much extra work.

@node Command-Line Interfaces

@section Standards for Command Line Interfaces

@cindex command-line interface

@findex getopt

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

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

will normally permit options anywhere among the arguments unless the

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

specifies; it is a GNU extension.

@cindex long-named options

Please define long-named options that are equivalent to the

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

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

@code{getopt_long}.

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

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

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

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

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

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

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

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

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

@cindex standard command-line options

@cindex options, standard command-line

@cindex CGI programs, standard options for

@cindex PATH_INFO, specifying standard options as

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

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

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

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

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

command line.

@menu

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

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

@end menu

@node --version

@subsection @option{--version}

@cindex @samp{--version} output

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