STYLE(7) Standards, Environments, and Macros STYLE(7)

NAME

STYLE - C Style and Coding Standards for illumos

SYNOPSIS

This document describes a set of coding standards for C programs
written in illumos gate, the illumos source repository.

This document is based on C Style and Coding Standards for SunOS by
Bill Shannon.

INTRODUCTION

The purpose of the document is to establish a consistent style for C
program source files within the illumos gate. Collectively, this
document describes the "illumos C style", and the scope is limited to
the application of illumos coding style to the C language.

Source code tends to be read many more times than it is written or
modified. Using a consistent style makes it easier for multiple people
to co-operate in the development and maintenance of programs. It
reduces cognitive complexity by eliminating superficial differences,
freeing the programmer to concentrate on the task at hand. This in
turn aids review and analysis of code, since small stylistic
distractions are eliminated. Further, eliding such distractions makes
it easier for programmers to work on unfamiliar parts of the code base.
Finally, it facilitates the construction of tools that incorporate the
rules in this standard to help programmers prepare programs. For
example, automated formatters, text editor integration, and so on, can
refer to this document to understand the rules of illumos C.

Of necessity, these standards cannot cover all situations. Experience
and informed judgment count for much. Inexperienced programmers who
encounter unusual situations should refer to code written by
experienced C programmers following these rules, or consult with
experienced illumos programmers for help with creating a stylistically
acceptable solution.

The illumos code base has a long history, dating back to the original
Unix from AT&T and Bell Labs. Furthermore, for many years the C style
was not formally defined, and there was much variation and many corner
cases as it evolved. As such, it is possible to find examples of code
that do not conform to this standard in the source tree. If possible,
strongly consider converting to this style before beginning substantial
work on such code. If that is not practical, then favor consistency
with surrounding code over conformity. All new code should conform to
these rules.

Character Set
Source files predominantly use ASCII printing characters. However,
UTF-8 may be used when required for accurate representation of names
and proper nouns in comments and string literals. Exercise some care
here, however: be aware that source files are consumed by many tools
beyond just compilers, and some may not be able to cope with multi-byte
extended characters. In particular, ISO/IEC 9899:1999 ("ISO C99") is
used for most illumos source and technically limits its "extended"
character set to characters that can fit into a single byte. C11
relaxes this, and most illumos tools are already fairly tolerant here,
but use sound judgment with non-ASCII characters: people should not be
forced to change their names, but do not add emoji or other extraneous
content. UTF-8 may not be used in identifiers.

Generally favor ASCII-only in header files. For new code, Avoid non-
ASCII characters from non-UTF-8 character encodings such as ISO-8859-1
or similar. Pseudo-graphical line printing characters and similar
glyphs are not permitted, though diagrams made with "ASCII art" using
`+', `-', `|' and so on are permitted. Non-printing characters, such
as control characters (including form-feeds, backspace, and similar)
should not appear in source files. Terminal escape sequences to change
text color or position are similarly prohibited.

Inside of string constants, prefer C escape sequences instead of
literal characters for tabs, form-feeds, carriage returns, newlines,
and so on. Obviously, use a literal space character when a space is
required in a string: do not use octal or hex escape sequences when a
space literal will do.

Generally prefer the use of C character constants to numeric code
points. For example, use

if (*p == '\n')
return (EOL); /* end of line */

instead of,

#define NL 10
if (*p == NL)
return (EOL); /* end of line */

An exception here may be if reading octet-oriented data where specific
values are known in advance, such as when parsing data read from a
socket.

Lines in Source Files
Lines in source files are limited to 80 columns. If a logical line
exceeds this, it must be broken and continued on a new line.

Continuation Lines

Continuation lines are used when a logical statement or expression will
not fit in the available space, such as a procedure call with many
arguments, or a complex boolean or arithmetic expression. When this
happens, the line should be broken as follows:

+o After a comma in the case of a function call or function
definition. Note, never break in the middle of a parameter
expression, such as between the type and argument name.

+o After the last operator that fits on the line for arithmetic,
boolean and ternary expressions.

A continuation line should never start with a logical or binary
operator. The next line should be further indented by four literal
space characters (half a tab stop). If needed, subsequent continuation
lines should be broken in the same manner, and aligned with each other.
For example,

if (long_logical_test_1 || long_logical_test_2 ||
long_logical_test_3) {
statements;
}

a = (long_identifier_term1 - long_identifier_term2) *
long_identifier_term3;

function(long_complicated_expression1, long_complicated_expression2,
long_complicated_expression3, long_complicated_expression4,
long_complicated_expression5, long_complicated_expression6)

It is acceptable to break a line earlier than necessary in order to
keep constructs together to aid readability or understanding. For
example,

if ((flag & FLAG1) != 0 ||
(flag & FLAG2) != 0 ||
(flag & FLAG3) != 0) {
statements;
}

Continuation lines usually occur when blocks are deeply nested or very
long identifiers are used, or functions have many parameters. Often,
this is a sign that code should be rewritten or broken up, or that the
variable name is not fit for purpose. A strategically introduced
temporary variable may help clarify the code. Breaking a particularly
large function with deeply nested blocks up into multiple, smaller
functions can be an improvement. Using a structure to group arguments
together instead of having many positional parameters can make function
signatures shorter and easier to understand.

Indentation and White Space

Initial indentation must use only tab characters, with tabs set to
eight spaces. Continuation lines are indented with tabs to the
continued line, and then further indented by another four spaces, as
described above. If indentation causes the code to be too wide to fit
in 80 columns, it may be too complex and would be clearer if it were
rewritten, as described above. The rules for how to indent particular
C constructs such as if, for and switch are described in Compound
Statements.

Tab characters may also be used for alignment beyond indentation within
source files, such as to line up comments, but avoid using spaces for
this. Note that "ASCII art" diagrams in block comments are explicitly
exempt from this rule, and may use spaces for alignment as needed. A
space followed by a tab outside of a string constant is forbidden.

Trailing white space is not permitted, whether at the ends of lines or
at the end of the file. That is, neither trailing blanks or tabs at
the ends of lines nor additional newlines at the end of a file are
allowed. The last character in each source file should be a newline
character.

Comments
Comments should be used to give overviews of code and provide
additional information that is not readily apparent from the source
itself. Comments should only be used to describe what code does or why
it is implemented the way that it is, but should not describe how code
works. Very rare exceptions are allowed for cases where the
implementation is particularly subtle.

Source files should begin with a block comment that includes license
information for that file, as well as a list of copyright holders.
However, source files should not contain comments listing authors or
the modification history for the file: this information belongs in the
revision control system and issue tracker. Following the copyright
material, an explanatory comment that describes the file's purpose,
provides background, refences to relevant standards, or similar
information, is helpful. A suitable template for new files can be
found in usr/src/prototypes within the illumos-gate code repository.

Front-matter aside, comments should only contain information that is
germane to reading and understanding the program. External
information, such about how the corresponding package is built or what
directory it should reside in should not be in a comment in a source
file. Discussions of non-trivial design decisions are appropriate if
they aid in understanding the code, but again avoid duplicating
information that is present in, and clear from, the code. In general,
avoid including information that is likely to become out-of-date in
comments; for example, specific section numbers of rapidly evolving
documents may change over time.

Comments should not be enclosed in large boxes drawn with asterisks or
other characters. Comments should never include special characters,
such as form-feed or backspace, and no terminal drawing characters.

There are three styles of comments: block, single-line, and trailing.

Block Comments

The opening `/*' of a block comment that appears at the top-level of a
file (that is, outside of a function, structure definition, or similar
construct) should be in column one. There should be a `*' in column 2
before each line of text in the block comment, and the closing `*/'
should be in columns 2-3, so that the `*'s line up. This enables `grep
^.\*' to match all of the top-level block comments in a file. There is
never any text on the first or last lines of a block comment. The
initial text line is separated from the * by a single space, although
later text lines may be further indented, as appropriate for clarity.

/*
* Here is a block comment.
* The comment text should be spaced or tabbed over
* and the opening slash-star and closing star-slash
* should be alone on a line.
*/

Block comments are used to provide high-level, natural language
descriptions of the content of files, the purpose of functions, and to
describe data structures and algorithms. Block comments should be used
at the beginning of each file and before functions as necessary.

The very first comment in a file should be front-matter containing
license and copyright information, as mentioned above.

Following the front-matter, files should have block comments that
describe their contents and any special considerations the reader
should take note of while reading.

A block comment preceding a function should document what it does,
input parameters, algorithm, and returned value. For example,

/*
* index(c, str) returns a pointer to the first occurrence of
* character c in string str, or NULL if c doesn't occur
* in the string.
*/

In many cases, block comments inside a function are appropriate, and
they should be indented to the same indentation level as the code that
they describe.

Block comments should contain complete, correct sentences and should
follow the English language rules for punctuation, grammar, and
capitalization. Sentences should be separated by either a single space
or two space characters, and such spacing should be consistent within a
comment. That is, either always separate sentences with a single space
or with two spaces, but do not mix styles within a comment (and ideally
do not mix styles within a source file). Paragraphs within a block
comment should be separated by an empty line containing only a space,
`*' and newline. For example,

/*
* This is a block comment. It consists of several sentences
* that are separated by two space characters. It should say
* something significant about the code.
*
* This comment also contains two separate paragraphs, separated
* by an "empty" line. Note that the "empty" line still has the
* leading ' *'.
*/

Do not indent paragraphs with spaces or tabs.

Single-Line Comments
A single-line comment is a short comment that may appear on a single
line indented so that it matches the code that follows. Short phrases
or sentence fragments are acceptable in single-line comments.

if (argc > 1) {
/* get input file from command line */
if (freopen(argv[1], "r", stdin) == NULL)
err(EXIT_FAILURE, "can't open %s\n", argv[1]);
}

The comment text should be separated from the opening `/*' and closing
`*/' by a space.

The closing `*/'s of several adjacent single-line comments should not
be forced to be aligned vertically. In general, a block comment should
be used when a single line is insufficient.

Trailing Comments

Very short comments may appear on the same line as the code they
describe, but should be tabbed over far enough to separate them from
the statements. If more than one short comment appears in a block of
code, they should all be tabbed to the same indentation level.
Trailing comments are most often sentence fragments or short phrases.

if (a == 2)
return (TRUE); /* special case */
else
return (isprime(a)); /* works only for odd a */

Trailing comments are most useful for documenting declarations and non-
obvious cases. Avoid the assembly language style of commenting every
line of executable code with a trailing comment.

Trailing comments are often also used on preprocessor #else and #endif
statements if they are far away from the corresponding test. See
Preprocessor for more guidance on this.

XXX and TODO comments

Do not add "XXX" or "TODO" comments in new code.

Naming Conventions
It has been said that naming things is the hardest problem in computer
science, and the longevity of illumos means that there is wide
variation across the source base when it comes to identifiers. Much of
this was driven by the demands of early C dialects, that restricted
externally visible identifiers to 6 significant characters. While this
ancient restriction no longer applies in modern C, there is still an
aesthetic preference for brevity and some argument about backwards
compatibility with third-party compilers. Regardless, consistent
application of conventions for identifiers can make programs more
understandable and easier to read. Naming conventions can also give
information about the function of the identifier, whether constants,
named types, variables, or similar, that can be helpful in
understanding code. Programmers should therefore be consistent in
using naming conventions within a project. Individual projects will
undoubtedly have their own naming conventions incorporating terminology
specific to that project.

In general, the following guidelines should be followed:

+o The length of a name should be proportional to its scope. An
identifier declared at global scope would generally be longer
than one declared in a small block; an index variable used in
a one-line loop might be a single character.

+o Names should be short but meaningful. Favor brevity.

+o One character names should be avoided except for temporary
variables of short scope. If one uses a single character
name, then use variables i, j, k, m, n for integers, c, d, e
for characters, p, q for pointers, and s, t for character
pointers. Avoid variable l (lower-case L) because it is hard
to distinguish between `1' (the digit one) and `I' (capital
i) on some printers and displays.

+o Pointers may have a `p' appended to their names for each
level of indirection. For example, a pointer to the variable
dbaddr can be named dbaddrp (or perhaps simply dp), if the
scope is small enough. Similarly, dbaddrpp would be a
pointer to a pointer to dbaddr.

+o Separate "words" in a long identifier with underscores:

create_panel_item

Mixed case names like `CreatePanelItem', or `javaStyleName',
are strongly discouraged and should not be used for new code.

+o Leading underscores are reserved by the C standard and
generally should not be used in identifiers for user-space
programs. They may be used in user-space libraries or in the
kernel with some caution, though be careful to avoid
conflicts with constructs from standard C, such as `_Bool',
`_Alignof', and so on. Trailing underscores should be
similarly avoided in user-space programs.

+o Two conventions are used for named types in the form of
typedefs. Within the kernel and in many places in userland,
named types are given a name ending in `_t', for example,

typedef enum { FALSE, TRUE } bool_t;
typedef struct node node_t;

Technically such names are reserved by POSIX, but some
liberties are taken here given both the age and provenance of
the illumos code base. Note that typedefs for function
pointer types may end in `_f' to signify that they refer to
function types.

In some user programs named types have their first letter
capitalized, as in,

typedef enum { FALSE, TRUE } Bool;
typedef struct node Node;
This practice is deprecated; all new code must use the `_f'
and `_t' suffices for named types.

+o #define names for constants should be in all CAPS. Separate
words with underscores, as for variable names.

+o Function-like macro names may be all CAPS or all lower case.
Prefer all upper case macro names for new code. Some macros
(such as getchar(3C) and putchar(3C)) are in lower case since
they may also exist as functions. Others, such as major(3C),
minor(3C), and makedev(3C) are macros for historical reasons.

+o Variable names, structure tag names, and function names
should be lower case.

Note: in general, with the exception of named types, it is
best to avoid names that differ only in case, like foo and
FOO. The potential for confusion is considerable. However,
it is acceptable to use a name which differs only in
capitalization from its base type for a typedef, such as,

typedef struct node Node;

It is also acceptable to give a variable of this type a name
that is the all lower case version of the type name. For
example,

Node node;

+o Struct members should be prefixed with an identifier as
described in Structures and Unions.

+o The individual items of enums should be made unique names by
prefixing them with a tag identifying the package to which
they belong. For example,

enum rainbow { RB_red, RB_orange, RB_green, RB_blue };

The mdb(1) debugger supports enums in that it can print out
the value of an enum, and can also perform assignment
statements using an item in the range of an enum. Thus, the
use of enums over equivalent #defines may aid debugging
programs. For example, rather than writing:

#define SUNDAY 0
#define MONDAY 1

write:

enum day_of_week { DW_SUNDAY, DW_MONDAY, ... };

Enums of this sort can be particularly useful for bitfields,
as the mdb(1) debugger can decode them symbolically. For
example, an instance of:

enum vmx_caps {
VMX_CAP_NONE = 0,
VMX_CAP_TPR_SHADOW = (1UL << 0),
VMX_CAP_APICV = (1UL << 1),
VMX_CAP_APICV_X2APIC = (1UL << 2),
VMX_CAP_APICV_PIR = (1UL << 3),
};

with all bits set is printed by mdb(1) as

0xf (VMX_CAP_{TPR_SHADOW|APICV|APICV_X2APIC|APICV_PIR})

+o Implementors of libraries should take care to hide symbols
that are private to the library. If a symbol is local to a
single module, one may simply declare it as static. For
symbols that are shared between several translation units in
the same library, and therefore must be declared extern, the
programmer should use the linker and mapfiles to hide private
symbols. For symbols that are logically private to group of
libraries, one may use a naming convention, such as prefixing
the name with an underscore and a tag that is unique to the
package, such as, `_panel_caret_mpr', but it is not necessary
to use stylistic conventions to hide symbols that will not be
exported. Programmers may optionally use such a naming
convention as an additional signal that symbols are internal
to a library, but this is not required.

+o One should always use care to avoid conflicts with
identifiers reserved by C.

+o Generally use nouns for type names and verbs or verb phrases
for functions.

Declarations
There is considerable variation in the format of declarations within
the illumos gate. As an example, there are many places that use one
declaration per line, and employ tab characters to line up the variable
names:

int level; /* indentation level */
int size; /* size of symbol table */
int lines; /* lines read from input */

and it is also common to declarations combined into a single line,
particularly when the variable names are self-explanatory or temporary:

int level, size, lines;

Indentation between type names or qualifiers and identifiers also
varies. Some use no such indentation:

int level,
volatile uint8_t byte;
char *ptr;

while many programmers feel that aligning variable declarations makes
code more readable:

int x;
extern int y;
volatile int count;
char **pointer_to_string;

However note that declarations such as the following probably make code
harder to read:

struct very_long_structure_name *p;
struct another_very_long_structure_name *q;
char *s;
int i;
short r;

While these styles vary, there are some rules which should be applied
consistently:

+o Always use function prototypes in preference to old-style
function declarations for new code.

+o Variables and functions should not be declared on the same
line.

+o Variables which are initialized at the time of declaration
should be declared on separate lines. That is one should
write:

int size, lines;
int level = 0;

instead of:

int level = 0, size, lines;

+o Variable declarations should be scoped to the smallest
possible block in which they are used.

+o Variable names within inner blocks should not shadow those at
higher levels.

+o For code compiled with flags that enable ISO/IEC 9899:1999
("ISO C99") features, additionally:

+o A for loop may declare and initialize its counting
variable. Note that the most appropriate type for
counting variables is often size_t or uint_t rather
than int. In particular, take care when indexing
into arrays: size_t is guaranteed to be large
enough to index any array, whereas uint_t is not.

+o Variables do not have to be declared at the start
of a block. However, care should be taken to use
this feature only where it makes the code more
readable.

External Declarations

External declarations should begin in column 1. Each declaration
should be on a separate line. A comment describing the role of the
object being declared should be included, with the exception that a
list of defined constants does not need comments if the constant names
themselves are sufficient documentation. Constant names and their
defined values should be tabbed so that they line up underneath each
other. For a block of related objects, a single block comment is
sufficient. However, if trailing comments are used, these should also
be tabbed to line up underneath each other.

Structures and Unions

For structure and union template declarations, each element should be
on its own line with a comment describing it. The struct keyword and
opening brace `{' should be on the same line as the structure tag, and
the closing brace should be alone on a line in column 1. Each member
is indented by one tab:

struct boat {
int b_wllength; /* water line length in feet */
int b_type; /* see below */
long b_sarea; /* sail area in square feet */
};

Struct members should be prefixed with an abbreviation of the struct
name followed by an underscore (`_'). Typically the first character of
each word in the struct's name is used for the prefix. While not
required by the language, this convention disambiguates the members for
tools such as cscope(1). For example, consider a structure with a
member named `len', this could lead to many ambiguous references.

Use of `static'
In any file which is part of a larger whole rather than a self-
contained program, maximum use should be made of the static keyword to
make functions and variables local to single files. Variables in
particular should be accessible from other files only when there is a
clear need that cannot be filled in another way. Such usage, and in
particular its rationale, should be made clear with comments, and
possibly with a private header file.

Qualifiers

Qualifiers, like `const', `volatile', and `restrict' are used to
communicate information to the compiler about how an object is used.
This can be very useful for facilitating optimizations that can
dramatically improve the runtime performance of code. Appropriate
qualification can prevent bugs. For example, a `const' qualified
pointer points to an object that cannot be modified; an attempt to do
so will give a compile-time error, rather than runtime data corruption.
Additionally, use of such qualifiers can communicate attributes of an
interface to a programmer who uses that interface; a programmer who
passes a pointer to a function that expects a `const' qualified
parameter knows that the function will not modify the value the pointer
refers to. Use qualifiers, but beware of some caveats.

Pointer variables that are `const' qualified should not cast away the
qualifier; the compiler may make optimizations based on the
qualification that are invalid if applied in a non-const context.
Similarly, it is undefined behavior to discard the qualifier for
variables that are `volatile'. Note that this means that one cannot,
for example, pass a volatile-qualified pointer to many functions, such
as memcpy(3C) or memset(3C).

Function Definitions
A complex function should be preceded by a prologue in a block comment
that gives the name and a short description of what the function does.

The type of the value returned should be alone on a line in column 1,
including any qualifiers, such as `const' or `static'. Functions that
return int should have that return type explicitly specified:
traditional C's default of int for the return type of unqualified
functions is deprecated. If the function does not return a value then
it should be given the return type void. If the return value requires
explanation, it should be given in the block comment. Functions and
variables that are not used outside of the file they are defined in
should be declared as static. This lets the reader know explicitly
that they are private, and also eliminates the possibility of name
conflicts with variables and procedures in other files.

Functions must be declared using ANSI X3.159-1989 ("ANSI C89") syntax
rather than K&R. There are still places within the illumos gate that
use K&R syntax and these should be converted as work is done in those
areas.

All local declarations and code within the function body should be
tabbed over at least one tab, with the level of indentation reflecting
the structure of the code. Labels should appear in column 1. If the
function uses any external variables or functions that are not
otherwise declared extern at the file level or in a header file, these
should have their own declarations in the function body using the
extern keyword. If the external variable is an array, the array bounds
must be repeated in the extern declaration.

If an external variable or value of a parameter passed by pointer is
changed by the function, that should be noted in the block comment.

All comments about parameters and local variables should be tabbed so
that they line up vertically. The declarations should be separated
from the function's statements by a blank line.

Note that functions that take no parameters must always have a void
parameter, as shown in the first example below.

The following examples illustrate many of the rules for function
definitions.

/*
* sky_is_blue()
*
* Return true if the sky is blue, else false.
*/
bool
sky_is_blue(void)
{
extern int hour;

if (hour < MORNING || hour > EVENING)
return (false); /* black */
else
return (true); /* blue */
}

/*
* tail(nodep)
*
* Find the last element in the linked list
* pointed to by nodep and return a pointer to it.
*/
Node *
tail(Node *nodep)
{
Node *np; /* current pointer advances to NULL */
Node *lp; /* last pointer follows np */

np = lp = nodep;
while ((np = np->next) != NULL)
lp = np;
return (lp);
}

/*
* ANSI C Form 1.
* Use this form when the arguments easily fit on one line,
* and no per-argument comments are needed.
*/
int
foo(int alpha, char *beta, struct bar gamma)
{
...
}

/*
* ANSI C Form 2.
* This is a variation on form 1, using the standard continuation
* line technique (indent by 4 spaces). Use this form when no
* per-argument comments are needed, but all argument declarations
* won't fit on one line.
*/
int
foo(int alpha, char *beta,
struct bar gamma)
{
...
}

/*
* ANSI C Form 3.
* Use this form when per-argument comments are needed.
* Note that each line of arguments is indented by a full
* tab stop. Note carefully the placement of the left
* and right parentheses.
*/
int
foo(
int alpha, /* first arg */
char *beta, /* arg with a long comment needed */
/* to describe its purpose */
struct bar gamma) /* big arg */
{
...
}

A single blank line should separate function definitions.

Type Declarations
Many programmers use named types, such as, typedefs, liberally. They
feel that the use of typedefs simplifies declaration lists and can make
program modification easier when types must change. Other programmers
feel that the use of a typedef hides the underlying type when they want
to know what the type is. This is particularly true for programmers
who need to be concerned with efficiency, like kernel programmers, and
therefore need to be aware of the implementation details. The choice
of whether or not to use typedef is left to the implementor.

If one elects to use a typedef in conjunction with a pointer type, the
underlying type should be typedef-ed, rather than typedef-ing a pointer
to underlying type, because it is often necessary and usually helpful
to be able to tell if a type is a pointer.

The use of ISO/IEC 9899:1999 ("ISO C99") unsigned integer identifiers
of the form uintXX_t is preferred over the older BSD-style u_intXX_t.
New code should use the former, and old code should be converted to the
new form if other work is being done in that area.

Boolean Types
ISO/IEC 9899:1999 ("ISO C99") introduced the `_Bool' keyword and
preprocessor macros for the bool, true, and false symbols in the
<stdbool.h> header (<sys/stdbool.h> in the kernel). Prior to this, C
had no standard boolean type, but illumos provided an `enum',
boolean_t, with variants B_FALSE and B_TRUE that is widely used.

Sadly, these two types differ significantly:

+o bool tends to be defined by ABIs as being a single byte wide,
while enumerations, and thus boolean_t, use the same
representation as an int.

+o bool is defined to be unsigned, while the enumerated type
boolean_t is signed.

+o The type "rank" of _Bool is defined to be lower than all
other integer types.

+o The only legal values of variables of type bool are 0 and 1
(false and true respectively), and while boolean_t is only
defined with two variants, nothing structurally prevents an
assignment from a different value.

+o Type conversion to _Bool has different semantics than
assignment to other integer types: conversion results in a 0
if and only if the original value compares equal to 0,
otherwise the result is a 1. For an int, truncating,
rounding behavior, or sign extending behavior is used.
Thus, programmers must exercise significant care when mixing code using
the standard type and boolean_t.

Broadly, new code should prefer the use of bool when available.
However, code that makes extensive use of boolean_t should generally
continue to do so. Do not mix bool and boolean_t in the same struct,
for example. Similarly, if a file makes extensive use of one, then do
not use the other. Furthermore be aware that using bool requires at
least ISO/IEC 9899:1999 ("ISO C99"), which is not mandated across the
system, so exercise care in public interfaces. Be particularly aware
that transitive includes of header files could mean that code using
constructs such as bool might leak into code that targets an older
version of the language; the programmer must not allow this to happen.
For example, should a use of bool inadvertantly end up in <stdlib.h>,
<sys/types.h>, or another standard-mandated or traditional Unix header
file and be available outside of a ISO/IEC 9899:1999 ("ISO C99")
compilation environment, older programs could fail to compile.

Do not use int or another type to present boolean values in new code.

Guidelines for mixing boolean types

As mentioned above, care must taken when mixing bool and boolean_t
types. In particular:

+o Assigning from a variable of type bool to one of boolean_t,
or vice versa, is generally safe. This includes assigning
the value returned from a function of one type to the other.

+o Passing arguments of one type to a function expecting the
other is generally safe.

+o Simple comparisons between the two types are generally safe.

However, taking a pointer to a variable of one type and casting it to
the other is not safe and should never be done. Similarly, changing
the definition of one type to another in a struct or union is not safe
unless one can guarantee that the element of such a compound type is
never referred to by pointer and that the type is never used as part of
a public interface, such as an ioctl(2).

Statements
Each line should contain at most one statement. In particular, do not
use the comma operator to group multiple statements on one line, or to
avoid using braces. For example,

argv++; argc--; /* WRONG */

if (err)
fprintf(stderr, "error"), exit(1); /* VERY WRONG */

Nesting the ternary conditional operator (?:) can lead to confusing,
hard to follow code. For example:

num = cnt < tcnt ? (cnt < fcnt ? fcnt : cnt) :
tcnt < bcnt ? tcnt : bcnt > fcnt ? fcnt : bcnt; /* WRONG */

Avoid expressions like these, and in general do not nest the ternary
operator unless doing so is unavoidable.

If the return statement is used to return a value, the expression
should always be enclosed in parentheses.

Functions that return no value should not include a return statement as
the last statement in the function, though early return via a bare
return; on a line by itself is permitted.

Compound Statements

Compound statements are statements that contain lists of statements
enclosed in braces (`{}'). The enclosed list should be indented one
more level than the compound statement itself. The opening left brace
should be at the end of the line beginning the compound statement, and
the closing right brace should be alone on a line, positioned under the
beginning of the compound statement (see examples below). Note that
the left brace that begins a function body is the only occurrence of a
left brace which should be alone on a line.

Braces are also used around a single statement when it is part of a
control structure, such as an if-else or for statement, as in:

if (condition) {
if (other_condition)
statement;
}

Some programmers feel that braces should be used to surround all
statements that are part of control structures, even singletons,
because this makes it easier to add or delete statements without
thinking about whether braces should be added or removed. Some
programmers reason that, since some apparent function calls might
actually be macros that expand into multiple statements, always using
braces allows such macros to always work safely. Thus, they would
write:

if (condition) {
return (0);
}

Here, the braces are optional and may be omitted to save vertical
space. However:

+o if one arm of an if-else statement contains braces, all arms
should contain braces;

+o if the condition or singleton occupies more than one line,
braces should always be used;

if (condition) {
fprintf(stderr, "wrapped singleton: %d\n",
errno);
}

if (strncmp(str, "long condition",
sizeof ("long condition") - 1) == 0) {
fprintf(stderr, "singleton: %d\n", errno);
}

+o if the body of a for or while loop is empty, no braces are
needed:

while (*p++ != c)
;

Examples

if, if-else, if-else if-else statements

if (condition) {
statements;
}

if (condition) {
statements;
} else {
statements;
}

if (condition) {
statements;
} else if (condition) {
statements;
}

Note that the right brace before the else and the right brace before
the while of a do-while statement (see below) are the only places where
a right brace appears that is not alone on a line.

for statements

for (initialization; condition; update) {
statements;
}

When using the comma operator in the initialization or update clauses
of a for statement, it is suggested that no more than three variables
should be updated. More than this tends to make the expression too
complex. In this case it is generally better to use separate
statements outside the for loop (for the initialization clause), or at
the end of the loop (for the update clause).

The initialization, condition, and update portions of a for loop may be
omitted.

The infinite loop is written using a for loop.

for (;;) {
statements;
}

while statements

while (condition) {
statements;
}

When writing while loops, prefer nested assignment inside of
comparison. That is, prefer:

while ((c = getc()) != EOF) {
statements;
}

over,

c = get();
while (c != EOF) {
statements;
c = getc();
}

do-while statements

do {
statements;
} while (condition);

switch statements

switch (condition) {
case ABC:
case DEF:
statements;
break;
case GHI:
statements;
/* FALLTHROUGH */
case JKL: {
int local;

statements;
}
case XYZ:
statements;
break;
default:
statements;
break;
}

The last break is, strictly speaking, redundant, but it is recommended
form nonetheless because it prevents a fall-through error if another
case is added later after the last one.

When using the fall-through feature of switch, a comment of the style
shown above should be used. In addition to being a useful note for
future maintenance, it serves as a hint to the compiler that this is
intentional and should not therefore generate a warning.

All switch statements should include a default case with the possible
exception of a switch on an enum variable for which all possible values
of the enum are listed.

Don't assume that the list of cases covers all possible cases. New,
unanticipated, cases may be added later, or bugs elsewhere in the
program may cause variables to take on unexpected values.

Each case statement should be indented to the same level as the switch
statement. Each case statement should be on a line separate from the
statements within the case.

White Space

Vertical White Space

Judicious use of lines can improve readability by setting off sections
of code that are logically related. Use vertical white space to make
it clear that stanzas are logically separated.

A blank line should always be used in the following circumstances:

+o After the #include section at the top of a source file.

+o After blocks of #defines of constants, and before and after
#defines of macros.

+o Between structure declarations.

+o Between functions.

+o After local variable declarations.

Form-feeds should never be used to separate functions.

Horizontal White Space
Here are the guidelines for blank spaces:

+o A blank should follow a keyword whenever a parenthesis
follows the keyword. Note that both sizeof and return are
keywords, whereas things like strlen(3C) and exit(3C) are
not.

Blanks should not be used between procedure names (or macro
calls) and their argument list. This helps to distinguish
keywords from procedure calls.

/*
* No space between strncmp and '(' but
* there is one between sizeof and '('
*/
if (strncmp(x, "done", sizeof ("done") - 1) == 0)
...

+o Blanks should appear after commas in argument lists.

+o Blanks should not appear immediately after a left parenthesis
or immediately before a right parenthesis.

+o All binary operators except `.' and `->' should be separated
from their operands by blanks. In other words, blanks should
appear around assignment, arithmetic, relational, and logical
operators.

Blanks should never separate unary operators such as unary
minus, address (`&'), indirection (`*'), increment (`++'),
and decrement (`--') from their operands. Note that this
includes the unary `*' that is a part of pointer
declarations.

Examples:

char *d, *s;
a += c + d;
a = (a + b) / (c * d);
strp->field = str.fl - ((x & MASK) >> DISP);
while ((*d++ = *s++) != ' ')
n++;

+o The expressions in a for statement should be separated by
blanks:

for (expr1; expr2; expr3)

If an expression is omitted, no space should be left in its
place:

for (expr1; expr2;)

+o Casts should not be followed by a blank, with the exception
of function calls whose return values are ignored:

(void) myfunc((uintptr_t)ptr, (char *)x);

Hidden White Space

There are many uses of blanks that will not be visible when viewed on a
terminal, and it is often difficult to distinguish blanks from tabs.
However, inconsistent use of blanks and tabs may produce unexpected
results when the code is printed with a pretty-printer, and may make
simple regular expression searches fail unexpectedly. The following
guidelines are helpful:

+o Spaces and tabs at the end of a line are not permitted.

+o Spaces between tabs, and tabs between spaces, are not
permitted.

+o Use tabs to line things up in columns (such as for indenting
code, and to line up elements within a series of
declarations) and spaces to separate items within a line.

+o Use tabs to separate single line comments from the
corresponding code.

Parentheses
Since C has complex precedence rules, parentheses can clarify the
programmer's intent in complex expressions that mix operators.
Programmers should feel free to use parentheses if they feel that they
make the code clearer and easier to understand. However, bear in mind
that this can be taken too far, so some judgment must be applied to
prevent making things less readable. For example, compare:

x = ((x * 2) * 3) + (((y / 2) * 3) + 1);

to,

x = x * 2 * 3 + y / 2 * 3 + 1;

It is also important to remember that complex expressions can be used
as parameters to macros, and operator-precedence problems can arise
unless all occurrences of parameters in the body of a macro definition
have parentheses around them.

Constants
Numeric constants should not generally be written directly. Instead,
give the constant a meaningful name using a const variable, an enum or
the #define feature of the C preprocessor. This makes it easier to
maintain large programs since the constant value can be changed
uniformly by changing only the constant's definition.

The enum data type is the preferred way to handle situations where a
variable takes on only a discrete set of values, since additional type
checking is available through the compiler and, as mentioned above,
tools such as the mdb(1) debugger also support enums.

There are some cases where the constants 0 and 1 may appear as
themselves instead of as #defines. For example if a for loop indexes
through an array, then

for (i = 0; i < ARYBOUND; i++)

is reasonable.

In rare cases, other constants may appear as themselves. Some judgment
is required to determine whether the semantic meaning of the constant
is obvious from its value, or whether the code would be easier to
understand if a symbolic name were used for the value.

Goto
While not completely avoidable, use of goto is generally discouraged.
In many cases, breaking a procedure into smaller pieces, or using a
different language construct can eliminate the need for gotos. For
example, instead of:

again:
if (s = proc(args))
if (s == -1 && errno == EINTR)
goto again;

write:

do {
s = proc(args);
} while (s == -1 && errno == EINTR);

The main place where gotos can be usefully employed is to break out of
several levels of switch or loop nesting, or to centralize error path
cleanup code in a function. For example:

for (...)
for (...) {
...
if (disaster)
goto error;
}
...
error:
clean up the mess;

However the need to do such things may indicate that the inner
constructs should be broken out into a separate function. Never use a
goto outside of a given block to branch to a label within a block:

goto label; /* WRONG */
...
for (...) {
...
label:
statement;
...
}

When a goto is necessary, the accompanying label should be alone on a
line.

Variable Initialization
C permits initializing a variable where it is declared. Programmers
are equally divided about whether or not this is a good idea: "I like
to think of declarations and executable code as separate units.
Intermixing them only confuses the issue. If only a scattered few
declarations are initialized, it is easy not to see them." "The major
purpose of code style is clarity. I think the less hunting around for
the connections between different places in the code, the better. I
don't think variables should be initialized for no reason, however. If
the variable doesn't need to be initialized, don't waste the reader's
time by making him/her think that it does."

A convention used by some programmers is to only initialize automatic
variables in declarations if the value of the variable is constant
throughout the block; such variables should be declared const. Note
that as a matter of correctness, all automatic variables must be
initialized before use, either in the declaration or elsewhere.

The decision about whether or not to initialize a variable in a
declaration is therefore left to the implementor. Use good taste. For
example, don't bury a variable initialization in the middle of a long
declaration:

int a, b, c, d = 4, e, f; /* This is NOT good style */

Multiple Assignments
C also permits assigning several variables to the same value in a
single statement, as in,

x = y = z = 0;
Good taste is required here also. For example, assigning several
variables that are used the same way in the program in a single
statement clarifies the relationship between the variables by making it
more explicit:

x = y = z = 0;
vx = vy = vz = 1;
count = 0;
scale = 1;

is good, whereas:

x = y = z = count = 0;
vx = vy = vz = scale = 1;

sacrifices clarity for brevity. In any case, the variables that are so
assigned should all be of the same type (or all pointers being
initialized to NULL). It is not a good idea to use multiple
assignments for complex expressions, as this can be significantly
harder to read. E.g.,

foo_bar.fb_name.firstch = bar_foo.fb_name.lastch = 'c'; /* Yecch */

Preprocessor
The C preprocessor provides support for textual inclusion of files
(most often header files), conditional compilation, and macro
definitions and substitutions.

It should be noted that the preprocessor works at the lexicographical,
not syntactic level of the language. It is possible to define macros
that are not syntactically valid when expanded, and the programmer
should take care when using the preprocessor. Some general advice
follows.

Do not rename members of a structure using #define within a subsystem;
instead, use a union. The legacy practice of using #define to define
shorthand notations for referencing members of a union should not be
used in new code.

Be extremely careful when choosing names for #defines. For example,
never use something like

#define size 10

especially in a header file, since it is not unlikely that the user
might want to declare a variable named size.

Remember that names used in #define statements come out of a global
preprocessor name space and can conflict with names in any other
namespace. For this reason, this use of #define is discouraged.

Note that #define follows indentation rules similar to other
declarations; see the section on Indentation for details.

Care is needed when defining macros that replace functions since
functions pass their parameters by value whereas macros pass their
arguments by name substitution.

At the end of an #ifdef construct used to select among a required set
of options (such as machine types), include a final #else clause
containing a useful but illegal statement so that the compiler will
generate an error message if none of the options has been defined:

#ifdef vax
...
#elif sun
...
#elif u3b2
...
#else
#error unknown machine type;
#endif /* machine type */

Header files should make use of "include guards" to prevent their
contents from being evaluated multiple times. For example,

#ifndef _FOOBAR_H
#define _FOOBAR_H

/* Header contents....

#endif /* !_FOOBAR_H */

The symbol defined for the include guard should be uniquely derived
from the header file's name. Note that this is one area where library
authors often use a leading underscore in an identifier. While this is
technically in violation of the ISO C standard, the practice is common.

Don't change C syntax via macro substitution. For example,

#define BEGIN {

It makes the program unintelligible to all but the perpetrator.

Be especially aware that function-like macros are textually
substituted, and side-effects in their arguments may be multiply-
evaluated if the arguments are referred to more than once in the body
of the macro. Similarly, variables defined inside of a macro's body
may conflict with variables in the outer scope. Finally, macros are
not generally type safe. For most macros and most programs, these are
non-issues, but programmers who run into problems here may consider
judicious use of `inline' functions as an alternative.

Whitespace and the Preprocessor

Use the following conventions with respect to whitespace and the
preprocessor:

+o `#include' should be followed by a single space character.

+o `#define' should be followed by a single tab character.

+o `#if', `#ifdef', and other preprocessor statements may be
followed by either a tab or space, but be consistent with the
surrounding code.

Miscellaneous Comments on Good Taste
Avoid undefined behavior wherever possible. Note that the rules of C
are very subtle, and many things that at first appear well-defined can
actually conceal undefined behavior. When in doubt, consult the C
standard.

Traditional Unix style favors guard clauses, which check a precondition
and fail (possibly via an early return) over deeply nested control
structures. For example, prefer:

void
foo(void)
{
struct foo *foo;
struct bar *bar;
struct baz *baz;

foo = some_foo();
if (!is_valid_foo(foo))
return;
bar = some_bar(foo);
if (!is_valid_bar(bar)
return;
baz = some_baz(bar);
if (!is_valid_baz(baz));
return;

/* All of the preconditions are met */
do_something(baz);
}

over,

void
foo(void)
{
struct foo *f;

foo = some_foo();
if (is_valid_foo(foo)) {
bar = some_bar(foo);
if (is_valid_bar(bar)) {
baz = some_baz(bar);
if (is_valid_baz(baz)) {
/* Preconditions met */
do_something(baz);
}
}
}
}

Try to make the structure of your program match the intent. For
example, replace:

if (boolean_expression)
return (TRUE);
else
return (FALSE);

with:

return (boolean_expression);

Similarly,

if (condition)
return (x);
return (y);

is usually clearer than:

if (condition)
return (x);
else
return (y);

or even better, if the condition and return expressions are short;

return (condition ? x : y);

Do not default the boolean test for nonzero. Prefer

if (f() != 0)

rather than

if (f())

even though 0 is considered to "false" in boolean contexts in C. An
exception is commonly made for predicate functions, which encapsulate
(possibly complex) boolean expressions. Predicates must meet the
following restrictions:

+o Has no other purpose than to return true or false.

+o Returns 0 for false, non-zero for true.

+o Is named so that the meaning of the return value is obvious.

Call a predicate is_valid() or valid(), not check_valid(). Note that
isvalid() and similar names with the `is' prefix followed by a letter
or number (but not underscore) are reserved by the ISO C standard.

The set of POSIX ctype functions including isalpha(3C), isalnum(3C),
and isdigit(3C) are examples of predicates.

A particularly notorious case of not obeying the rules around
predicates is using strcmp(3C) to test for string equality, where the
result should never be defaulted (and indeed, a return value of 0
denotes equality).

Never use the boolean negation operator (`!') with non-boolean
expressions. In particular, never use it to test for a NULL pointer or
to test for success of comparison functions like strcmp(3C) or
memcmp(3C). E.g.,

char *p;
...
if (!p) /* WRONG */
return;

if (!strcmp(*argv, "-a")) /* WRONG */
aflag++;

When testing whether a bit is set in a value, it is good style to
explicitly test the result of a bitwise operation against 0, rather
than defaulting the boolean condition. Prefer

if ((flags & FLAG_VERBOSE) != 0)
if ((flags & FLAG_VERBOSE) == 0)

rather than the following:

if (flags & FLAG_VERBOSE)
if (!(flags & FLAG_VERBOSE))

Do not use the assignment operator in a place where it could be easily
confused with the equality operator. For instance, in the simple
expression

if (x = y)
statement;

it is hard to tell whether the programmer really meant assignment or
mistyped an equality test. Instead, use

if ((x = y) != 0)
statement;

or something similar, if the assignment is actually needed within the
if statement.

There is a time and a place for embedded assignments. The ++ and --
operators count as assignments; so, for many purposes, do functions
with side effects.

In some constructs there is no better way to accomplish the results
without making the code bulkier and less readable. To repeat the
earlier loop example:

while ((c = getchar()) != EOF) {
process the character
}

Embedded assignments used to provide modest improvement in run-time
performance, but this is no longer the case with modern optimizing
compilers. Do note write, for example,

d = (a = b + c) + 4; /* WRONG */

believing that it will somehow be "faster" than

a = b + c;
d = a + 4;

In general, avoid such premature micro-optimization unless performance
is clearly a bottleneck, and a profile shows that the optimization
provides a significant performance boost. Be aware how in the long run
hand-optimized code often turns into a pessimization, and maintenance
difficulty will increase as the human memory of what's going on in a
given piece of code fades. Note also that side effects within
expressions can result in code whose semantics are compiler-dependent,
since C's order of evaluation is explicitly undefined in most places.
Compilers do differ.

There is also a time and place for the ternary (`? :') operator and the
binary comma operator. If an expression containing a binary operator
appears before the `?', it should be parenthesized:

(x >= 0) ? x : -x

Nested ternary operators can be confusing and should be avoided if
possible.

The comma operator can be useful in for statements to provide multiple
initializations or incrementations.

SEE ALSO

Bill Shannon, C Style and Coding Standards for SunOS, 1996.

mdb(1)

illumos March 17, 2024 illumos