1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
Code style
==========
In general, FreeBSD style(9) should be followed unless it is irrelevant
(e.g., $FreeBSD$ tags).
Functions with external linkage are declared like this:
/**
* module_func(arg1, arg2):
* Description of what the function does, referring to arguments as
* ${arg1} or suchlike.
*/
int module_func(void *, int);
The identical comment appears in the C file where the function is defined.
Static functions may have the above form of comment, or simply a
/* Brief description of what the function does. */
line before the function.
"Unrewrappable" comments starting in the first column should be
/**
* Written like this.
*
* Because (some of) the line-breaks are important.
*/
whereas when such comments are indented, they should be
/*-
* Written like this.
*
* Because (some of) the line-breaks are important.
*/
Line lengths should generally be 78 characters, and not more than 80
characters.
In general, functions should return (int)(-1) or NULL to indicate error.
Errors should be printed via warnp (if errno is relevant) or warn0 (if errno
is not relevant) when they are first detected and also at higher levels where
useful. As an exception to this, malloc failures (i.e., errno = ENOMEM) can
result in failure being passed back up the call chain without being printed
immediately. (Naturally, other errors can be passed back where a function
definition so specifies; e.g., ENOENT in cases where a file not existing is
not erroneous.)
The first statement in main(), after variable declarations, should be
"WARNP_INIT;" in order to set the program name used for printing warnings.
We use %d rather than %i in printf and warn0/warnp strings.
In general, functions should be structured with one return statement per
status, e.g., one return() for success and one return() for failure. Errors
should be handled by using goto to enter the error return path, e.g.,
int
foo(int bar)
{
if (something fails)
goto err0;
/* ... */
if (something else fails)
goto err1;
/* ... */
if (yet another operation fails)
goto err2;
/* Success! */
return (0);
err2:
/* Clean up something. */
err1:
/* Clean up something else. */
err0:
/* Failure! */
return (-1);
}
As an exception to the above, if there is only one way for the function to
fail, the idioms
return (baz(bar));
and
int rc;
rc = baz(bar);
/* ... cleanup code here ... */
return (rc);
are allowed; furthermore, in cases such as foo_free(), the idiom
if (we shouldn't do anything)
return;
is preferred over
if (we shouldn't do anything)
goto done;
at the start of a function.
Headers should be included in the following groups, with a blank line after
each (non-empty) group:
1. <sys/*.h>, with <sys/types.h> first followed by others alphabetically.
2. <net/*.h>, in alphabetical order.
3. <*.h>, in alphabetical order.
4. header files from /lib/, in alphabetical order.
5. header files from the program being built, in alphabetical order.
6. header files (usually just one) defining the interface for this C file.
If ssize_t is needed, <unistd.h> should be included to provide it.
If size_t is needed, <stddef.h> should be included to provide it unless
<stdio.h>, <stdlib.h>, <string.h>, or <unistd.h> is already required.
If the C99 integer types (uint8_t, int64_t, etc.) are required, <stdint.h>
should be included to provide them unless <inttypes.h> is already required.
The type 'char' should only be used to represent human-readable characters
(input from users, output to users, pathnames, et cetera). The type
'char *' should normally be a NUL-terminated string. The types 'signed
char' and 'unsigned char' should never be used; C99 integer types should
be used instead.
When a variable is declared to have a pointer type, there should be a space
between the '*' and the variable name, e.g.,
int
main(int argc, char * argv[])
{
char * opt_p = NULL;
Note that this is inconsistent with FreeBSD style(9). When used as a unary
operator, '*' is not separated from its argument, e.g.,
while (*p != '\0')
p++;
When a struct is referenced, the idiom
/* Opaque types. */
struct foo;
struct bar * bar_from_foo(struct foo *);
is preferable to
#include "foo.h" /* needed for struct foo */
struct bar * bar_from_foo(struct foo *);
unless there is some reason why the internal layout of struct foo is needed
(e.g., if struct bar contains a struct foo rather than a struct foo *). Such
struct declarations should be sorted alphabetically.
The file foo.c should only export symbols of the following forms:
foo_* -- most symbols should be of this form.
FOO_* / BAR_FOO_*
-- allowed in cases where FOO or BAR_FOO is idiomatic (e.g.,
MD5, HMAC_SHA256).
foo() / defoo() / unfoo()
-- where "foo" is a verb and this improves code clarity.
Functions named foo_free should return void, and foo_free(NULL) should have
no effect. The right way to spell a comment about this is
/* Behave consistently with free(NULL). */
If static variables need to be initialized to 0 (or NULL) then they should be
explicitly declared that way; implicit initialization should not be used.
In non-trivial code, comments should be included which describe in English
what is being done by the surrounding code with sufficient detail that if the
code were removed, it could be replaced based on reading the comments without
requiring any significant creativity.
Comments and documentation should be written in en-GB-oed; i.e., with
the 'u' included in words such as "honour", "colour", and "neighbour",
and the ending '-ize' in words such as "organize" and "realize". The
Oxford (aka. serial) comma should be used in lists. Quotation marks
should be placed logically, i.e., not including punctuation marks which
do not form a logical part of the quoted text. Two spaces should be used
after a period which ends a sentence.
The first local variable declaration in cookie-using functions should be
struct foo * bar = cookie;
When versions of functions are written to exploit special CPU features
(using the cpusupport framework), that code should be placed into a
separate file (e.g., crypto_aes_aesni.c) so that it can be compiled with
different compiler flags. Such a file should start with
#include "cpusupport.h"
#ifdef CPUSUPPORT_FOO_BAR
/**
* CPUSUPPORT CFLAGS: FOO_BAR FOO_BAZ
*/
and end with
#endif /* CPUSUPPORT_FOO_BAR */
For example, we could have
#if defined(CPUSUPPORT_X86_SHANI) && defined(CPUSUPPORT_X86_SSSE3)
/**
* CPUSUPPORT CFLAGS: X86_SHANI X86_SSSE3
*/
Functions for which special CPU-feature-exploiting variants exist should
take the form
{
/* Variable declarations here. */
/* Asserts here, if any. */
#ifdef CPUSUPPORT_FOO_BAR
if (/* We've decided we can use the variant code */) {
/* Call variant code and return. */
}
#endif
/* Normal implementation of the function. */
}
If there are multiple CPU-feature-exploiting variants, the `if` could instead
be a `switch` which invokes the appropriate variant function.
|
