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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Cyrus IMAP Server: Hacking — Cyrus IMAP 3.12.1 documentation</title>
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/underscore.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Cyrus IMAP Server: Internationalization" href="internationalization.html" />
<link rel="prev" title="Developer Guidance" href="../guidance.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home">
Cyrus IMAP
</a>
<div class="version">
3.12.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../setup.html">Setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../developers.html">Developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../contribute.html">We need your help</a></li>
<li class="toctree-l2"><a class="reference internal" href="../documentation.html">Contribute docs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer.html">Contribute code and tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cyrusworks.html">Cyrus.Works</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../../developers.html#cyrus-internals">Cyrus Internals</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../API.html">Cyrus APIs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../thoughts.html">Thoughts & Notes</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../guidance.html">Guidance for Developers</a><ul class="current">
<li class="toctree-l4 current"><a class="current reference internal" href="#">Cyrus IMAP Server: Hacking</a></li>
<li class="toctree-l4"><a class="reference internal" href="internationalization.html">Cyrus IMAP Server: Internationalization</a></li>
<li class="toctree-l4"><a class="reference internal" href="locking.html">Cyrus IMAP Server: Locking</a></li>
<li class="toctree-l4"><a class="reference internal" href="mailbox-format.html">Cyrus IMAP Server: Mailbox File Formats</a></li>
<li class="toctree-l4"><a class="reference internal" href="namelocks.html">Cyrus IMAP Server: Namelocks</a></li>
<li class="toctree-l4"><a class="reference internal" href="prot.html">Cyrus IMAP Server: prot layer</a></li>
<li class="toctree-l4"><a class="reference internal" href="replication_examples.html">Cyrus IMAP Server: Replication Examples</a></li>
<li class="toctree-l4"><a class="reference internal" href="replication_protocol.html">Cyrus IMAP Server: Replication Protocol v2.4+</a></li>
<li class="toctree-l4"><a class="reference internal" href="special_chars.html">Cyrus IMAP Server: Special Characters</a></li>
<li class="toctree-l4"><a class="reference internal" href="var_directory_structure.html">Cyrus IMAP Server: var directory structure</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../developers.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">Cyrus IMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../../developers.html">Developers</a></li>
<li class="breadcrumb-item"><a href="../guidance.html">Developer Guidance</a></li>
<li class="breadcrumb-item active">Cyrus IMAP Server: Hacking</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/developer/guidance/hacking.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<span class="target" id="imap-developer-guidance-hacking"></span><section id="cyrus-imap-server-hacking">
<h1>Cyrus IMAP Server: Hacking<a class="headerlink" href="#cyrus-imap-server-hacking" title="Permalink to this heading"></a></h1>
<p>This file aims to be a guide to Cyrus coding style/conventions/useful
utilities for people trying to approach the code in a sane way. It's
not well organized right now but hopefully that will improve with time
;)</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This document is woefully out of date. While some parts of it are still
accurate, it has not been reviewed in quite a while. If you're looking at
the code and it doesn't seem to match this, don't assume the code is wrong.
Talk to the developers! We'll revise this document, but don't hold your
breath right now. (This comment written August 5, 2021.)</p>
</div>
<section id="memory-allocation">
<h2>Memory Allocation<a class="headerlink" href="#memory-allocation" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>All cyrus memory allocation should be done through the libcyrus
functions. These are all written to correctly call <code class="docutils literal notranslate"><span class="pre">fatal()</span></code> in
the event of an out-of-memory condition.</p></li>
<li><p>In addition to <code class="docutils literal notranslate"><span class="pre">xmalloc</span></code> and <code class="docutils literal notranslate"><span class="pre">xrealloc</span></code>, we provide replacements
for <code class="docutils literal notranslate"><span class="pre">strdup</span></code>, <code class="docutils literal notranslate"><span class="pre">strndup</span></code>, and a <code class="docutils literal notranslate"><span class="pre">malloc</span></code> that will guarantee
zeroed block of memory (<code class="docutils literal notranslate"><span class="pre">xzmalloc</span></code>).</p></li>
<li><p>If you are going to need to do a large number of small allocations,
and then free them all at once, you should look at the memory pool
routines, which are much faster, but will leak memory until you
free the entire pool at once.</p></li>
</ul>
</section>
<section id="strlcpy-vs-strncpy-vs-memcpy">
<h2>strlcpy vs strncpy vs memcpy<a class="headerlink" href="#strlcpy-vs-strncpy-vs-memcpy" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>use <code class="docutils literal notranslate"><span class="pre">strlcpy</span></code> when you know the size of the buffer, e.g.:</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">char</span> <span class="n">buf</span><span class="p">[</span><span class="mi">50</span><span class="p">];</span>
<span class="n">strlcpy</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="n">src</span><span class="p">,</span> <span class="n">sizeof</span><span class="p">(</span><span class="n">buf</span><span class="p">));</span>
</pre></div>
</div>
<ul class="simple">
<li><p>use <code class="docutils literal notranslate"><span class="pre">memcpy</span></code> to truncate a string into a buffer you know is large
enough. Note that when you do this the resulting buffer will NOT BE
NULL TERMINATED:</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">memcpy</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="n">src</span><span class="p">,</span> <span class="mi">4</span><span class="p">);</span>
<span class="n">buf</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'</span><span class="se">\0</span><span class="s1">'</span>
</pre></div>
</div>
<ul class="simple">
<li><p>you should try to avoid <code class="docutils literal notranslate"><span class="pre">strncpy</span></code>, since it is much slower than
<code class="docutils literal notranslate"><span class="pre">memcpy</span></code> (it zero-fills the rest of the buffer) and isn't as safe
as <code class="docutils literal notranslate"><span class="pre">strlcpy</span></code>.</p></li>
<li><p>Use of the functions in this way will reduce the confusion involved
in their various behaviors. In other words, this avoids things that
look like:</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">strncpy</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="n">src</span><span class="p">,</span> <span class="n">sizeof</span><span class="p">(</span><span class="n">buf</span><span class="p">)</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="map-refresh-and-map-free">
<h2>map_refresh and map_free<a class="headerlink" href="#map-refresh-and-map-free" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>In many cases, it is far more effective to read a file via the
operating system's mmap facility than it is to via the traditional
<code class="docutils literal notranslate"><span class="pre">read()</span></code> and <code class="docutils literal notranslate"><span class="pre">lseek</span></code> system calls. To this end, Cyrus provides
an operating system independent wrapper around the <code class="docutils literal notranslate"><span class="pre">mmap()</span></code>
services (or lack thereof) of the operating system.</p></li>
<li><p>Cyrus currently only supports read-only memory maps, all writes back
to a file need to be done via the more traditional facilities. This
is to enable very low-performance support for operating systems
which do not provide an <code class="docutils literal notranslate"><span class="pre">mmap()</span></code> facility via a fake userspace
<code class="docutils literal notranslate"><span class="pre">mmap</span></code>.</p></li>
<li><p>To create a map, simply call <code class="docutils literal notranslate"><span class="pre">map_refresh</span></code> on the map (details
are in lib/map.h). To free it, call <code class="docutils literal notranslate"><span class="pre">map_free</span></code> on the same map.</p></li>
<li><p>Despite the fact that the maps are read-only, it is often useful
to open the file descriptors O_RDWR, especially if the file
descriptors could possibly be used for writing elsewhere in the
code. Some operating systems REQUIRE file descriptors that are
<code class="docutils literal notranslate"><span class="pre">mmap()</span></code>-ed to be opened O_RDWR, so just do it.</p></li>
</ul>
</section>
<section id="network-functions">
<h2>Network Functions<a class="headerlink" href="#network-functions" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>Cyrus abstracts socket stream access to a concept we refer to as
"prot streams" Prot Streams take care of all of the necessary
SASL and TLS/SSL encryption that may need to happen before data
goes out/comes in from the network. The API is documented in
lib/prot.h</p></li>
</ul>
</section>
<section id="todo-authorization-modules">
<h2>(todo) Authorization Modules<a class="headerlink" href="#todo-authorization-modules" title="Permalink to this heading"></a></h2>
</section>
<section id="general-hints">
<h2>General Hints<a class="headerlink" href="#general-hints" title="Permalink to this heading"></a></h2>
<p>Some general hints that all made it into my 11/15 16:47 commit that I
think may be generally useful to people hacking on the cyrus source:</p>
<ul class="simple">
<li><p>Command line apps should link cli_fatal.o so they all fatal()
in the same way, unless there is a really good reason they need to
do something unique.</p></li>
<li><p>If you call <code class="docutils literal notranslate"><span class="pre">cyrus_init()</span></code> you must call <code class="docutils literal notranslate"><span class="pre">cyrus_done()</span></code> before
you exit.</p></li>
<li><p>No one should ever call <code class="docutils literal notranslate"><span class="pre">DB->init()</span></code> or <code class="docutils literal notranslate"><span class="pre">DB->done()</span></code> cyrusdb
functions except for in <code class="docutils literal notranslate"><span class="pre">libcyrus_init()</span></code>.</p></li>
<li><p>I've been trying to keep <code class="docutils literal notranslate"><span class="pre">#include</span></code> statements for libcyrus and
libimap alphabetical, and below any system includes, but this is
merely my personal style</p></li>
<li><p>Don't exit at the bottom of <code class="docutils literal notranslate"><span class="pre">main</span></code> with <code class="docutils literal notranslate"><span class="pre">exit(x)</span></code> use
<code class="docutils literal notranslate"><span class="pre">return</span></code> instead.</p></li>
<li><p>For all the command line utilities that need to be sure that they
are running as the cyrus user, it should be the first thing they
do, and they should exit with an appropriate <code class="docutils literal notranslate"><span class="pre">fatal()</span></code> call.</p></li>
<li><p>All services should have a <code class="docutils literal notranslate"><span class="pre">shut_down</span></code> call. It should be the
ONLY way of exiting the application. <code class="docutils literal notranslate"><span class="pre">fatal()</span></code> should always
make an attempt to call <code class="docutils literal notranslate"><span class="pre">shut_down()</span></code> if it can (though it should
have a recursive <code class="docutils literal notranslate"><span class="pre">fatal()</span></code> trap just in case). Similarly,
command line utilities probably don't need a <code class="docutils literal notranslate"><span class="pre">shut_down()</span></code>.</p></li>
</ul>
</section>
<section id="coding-standards">
<h2>Coding Standards<a class="headerlink" href="#coding-standards" title="Permalink to this heading"></a></h2>
<p>These are the generally agreed upon coding standards as thrashed
out on the cyrus-devel list in June 2010.</p>
<ul class="simple">
<li><p>Spacing is 4 characters with soft tabs at 8 - mixed tabs and spaces
This corresponds to the vi settings <cite>sw=4 sts=4 ts=8</cite> etc.</p></li>
<li><p>Group the '*' character with the variable not the type, i.e.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">char</span> <span class="o">*</span><span class="n">foo</span><span class="p">;</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">char</span><span class="o">*</span> <span class="n">foo</span><span class="p">;</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>The keywords 'if', 'for', and 'while' take a space after the keyword.
The parentheses around the following expression are not closely
connected to the expression without any spaces. The ';' inside
the 'for' expression have a space after them and not before.
For example:</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">if</span><span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">if</span><span class="p">(</span> <span class="n">condition</span> <span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">x</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">for</span><span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">x</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">;</span><span class="n">i</span> <span class="o"><</span> <span class="n">x</span> <span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">for</span><span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">;</span><span class="n">i</span> <span class="o"><</span> <span class="n">x</span> <span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">foo</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">while</span><span class="p">(</span><span class="n">foo</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span><span class="p">(</span> <span class="n">foo</span> <span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Use spaces around the double-character logical operator
'||' but don't use spaces around single-character bitwise
operator '|'.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">flags</span> <span class="o">=</span> <span class="n">FOO</span><span class="o">|</span><span class="n">BAR</span><span class="p">;</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">flags</span> <span class="o">=</span> <span class="n">FOO</span> <span class="o">|</span> <span class="n">BAR</span><span class="p">;</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">itchy</span> <span class="o">||</span> <span class="n">scratchy</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">itchy</span><span class="o">||</span><span class="n">scratchy</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Function definitions are followed by a brace on a line by itself,
all other braces are inline. Return types are inline with function
definition. Old K&R style function definitions are not allowed.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">thing</span><span class="p">(</span><span class="nb">int</span> <span class="n">val</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">void</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">thing</span><span class="p">(</span><span class="nb">int</span> <span class="n">val</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">void</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">thing</span><span class="p">(</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">val</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">void</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">antique</span><span class="p">(</span><span class="n">val</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">val</span><span class="p">;</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">void</span> <span class="n">thing</span><span class="p">(</span><span class="nb">int</span> <span class="n">val</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">void</span> <span class="n">noargs</span><span class="p">(</span><span class="n">void</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">void</span> <span class="n">noargs</span><span class="p">()</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Long argument lists should be split across multiple lines,
with the second and subsequent lines indented so that they
line up with the start of the first line of arguments.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">toomanyargs</span><span class="p">(</span><span class="nb">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">arg2</span><span class="p">,</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">struct</span> <span class="n">whatever</span> <span class="o">*</span><span class="n">arg3</span><span class="p">,</span> <span class="nb">int</span> <span class="n">arg4</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">void</span> <span class="n">toomanyargs</span><span class="p">(</span><span class="nb">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">arg2</span><span class="p">,</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">struct</span> <span class="n">whatever</span> <span class="o">*</span><span class="n">arg3</span><span class="p">,</span> <span class="nb">int</span> <span class="n">arg4</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">void</span> <span class="n">toomanyargs</span><span class="p">(</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">arg2</span><span class="p">,</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="n">struct</span> <span class="n">whatever</span> <span class="o">*</span><span class="n">arg3</span><span class="p">,</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">arg4</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Within a function, braces are used in old-fashioned K&R style.
Specifically:</p>
<ul>
<li><p>open braces are placed at the end of the line containing the
statement (such as an 'if') to which they belong, after a
single space.</p></li>
<li><p>closing braces are placed on a line by themselves, aligned
with the start of the statement to which their matching
open brace belongs.</p></li>
<li><p>this applies even when the closing brace is followed by
an 'else' keyword.</p></li>
</ul>
</li>
</ul>
<blockquote>
<div><p>Yes, it's ugly and hard to read, but you get used to it and
most of the code is currently like that. Deal with it.</p>
</div></blockquote>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">){</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">{</span> <span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">while</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">othercond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">else</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">othercond</span><span class="p">)</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">othercond</span><span class="p">)</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="k">else</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">body</span><span class="o">...</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">WRONG</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>The braces around a block used in an 'if'...'else if'...'else'
may be omitted if the statement is very simple and clear, such
as a single function call. This is a judgement call though,
so play it safe and use braces.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span><span class="p">,</span> <span class="n">maybe</span> <span class="o">*/</span>
<span class="n">function</span><span class="p">();</span> <span class="o">/*</span> <span class="n">correct</span><span class="p">,</span> <span class="n">maybe</span> <span class="o">*/</span>
<span class="k">else</span> <span class="o">/*</span> <span class="n">correct</span><span class="p">,</span> <span class="n">maybe</span> <span class="o">*/</span>
<span class="n">other_function</span><span class="p">();</span> <span class="o">/*</span> <span class="n">correct</span><span class="p">,</span> <span class="n">maybe</span> <span class="o">*/</span>
</pre></div>
</div>
<ul class="simple">
<li><p>The 'goto' keyword needs to be used very very sparingly and only
with forethought. The only clearly good example is to goto
a label at the end of a function to do cleanup under error
conditions.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">struct</span> <span class="n">bar</span> <span class="o">*</span><span class="n">b</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">{</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">char</span> <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="n">xmalloc</span><span class="p">(</span><span class="o">...</span><span class="p">);</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span> <span class="o">==</span> <span class="n">NULL</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">goto</span> <span class="n">error</span><span class="p">;</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="o">-></span><span class="n">quux</span> <span class="o">!=</span> <span class="mi">42</span><span class="p">)</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">goto</span> <span class="n">error</span><span class="p">;</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="o">...</span><span class="n">do</span> <span class="n">useful</span> <span class="n">things</span><span class="o">...</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">error</span><span class="p">:</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="n">free</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
<span class="p">}</span> <span class="o">/*</span> <span class="n">correct</span> <span class="o">*/</span>
</pre></div>
</div>
<blockquote>
<div><p>Very occasionally, it may be permissable to use 'goto' from within
a complicated or multiply-nested loop, to the top of a loop, but
only if using another control structure is <em>less</em> clear.</p>
</div></blockquote>
<ul class="simple">
<li><p>Generally, zero return is SUCCESS and integer return is an error code.</p></li>
<li><p>Use "<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code>" where possible.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>int is_tacky(const char *name) /* correct */
{ /* correct */
return !strcmp(name, "britney"); /* correct */
} /* correct */
int is_tacky(char *name) /* WRONG */
{ /* WRONG */
return !strcmp(name, "britney"); /* WRONG */
} /* WRONG */
</pre></div>
</div>
<ul class="simple">
<li><p>Use "<code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">buf</span></code>" for variable length strings where possible.</p></li>
<li><p>RAII <a class="reference external" href="http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization">http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization</a>
In practice, this means each structure should have a single cleanup
function which handles all possible states of the structure and
is called whenever the structure needs cleaning up. Likewise,
any resources allocated during a function should be cleaned up
in the same function, in a single code block at the end of the
function (see the comments on 'goto').</p></li>
<li><p>If you find yourself passing the same multiple parameters through many
functions, create a struct and pass around a pointer to that instead.</p></li>
<li><p>DON'T EVER REUSE THE SAME VARIABLE FOR TWO DIFFERENT PURPOSES IN THE SAME
FUNCTION. IN FACT, DON'T REUSE THE SAME VARIABLE _NAME_ FOR DIFFERENT
PURPOSES. KTHXBYE. (note: this doesn't apply to 'i', 'n', etc which are
used in multiple loops. It applies to using the same name for an absolute
offset and a "within this mmap" offset though, and it also applies to
using the same variable name for native order and network order numbers,
which is where I've seen it a few times and been super frustrated!)</p></li>
<li><p>Write RFCs in comments capitalized with space after the RFC, like
<code class="docutils literal notranslate"><span class="pre">RFC</span> <span class="pre">1234</span></code>, not like <code class="docutils literal notranslate"><span class="pre">rfc</span> <span class="pre">1234</span></code> or <code class="docutils literal notranslate"><span class="pre">RFC1234</span></code>.</p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../guidance.html" class="btn btn-neutral float-left" title="Developer Guidance" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="internationalization.html" class="btn btn-neutral float-right" title="Cyrus IMAP Server: Internationalization" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1993–2025, The Cyrus Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
