Debian Codegraph @

doc/html/_sources/imap/developer/guidance/hacking.rst.txt

raw
1 .. _imap-developer-guidance-hacking:
2
3 .. Note: This document was converted from the original by Nic Bernstein
4 (Onlight). Any formatting mistakes are my fault and not the
5 original author's.
6
7 Cyrus IMAP Server: Hacking
8 ==========================
9
10 This file aims to be a guide to Cyrus coding style/conventions/useful
11 utilities for people trying to approach the code in a sane way. It's
12 not well organized right now but hopefully that will improve with time
13 ;)
14
15 .. warning::
16
17 This document is woefully out of date. While some parts of it are still
18 accurate, it has not been reviewed in quite a while. If you're looking at
19 the code and it doesn't seem to match this, don't assume the code is wrong.
20 Talk to the developers! We'll revise this document, but don't hold your
21 breath right now. (This comment written August 5, 2021.)
22
23 Memory Allocation
24 -----------------
25
26 * All cyrus memory allocation should be done through the libcyrus
27 functions. These are all written to correctly call ``fatal()`` in
28 the event of an out-of-memory condition.
29 * In addition to ``xmalloc`` and ``xrealloc``, we provide replacements
30 for ``strdup``, ``strndup``, and a ``malloc`` that will guarantee
31 zeroed block of memory (``xzmalloc``).
32 * If you are going to need to do a large number of small allocations,
33 and then free them all at once, you should look at the memory pool
34 routines, which are much faster, but will leak memory until you
35 free the entire pool at once.
36
37 strlcpy vs strncpy vs memcpy
38 ----------------------------
39
40 * use ``strlcpy`` when you know the size of the buffer, e.g.:
41
42 ::
43
44 char buf[50];
45 strlcpy(buf, src, sizeof(buf));
46
47 * use ``memcpy`` to truncate a string into a buffer you know is large
48 enough. Note that when you do this the resulting buffer will NOT BE
49 NULL TERMINATED:
50
51 ::
52
53 memcpy(buf, src, 4);
54 buf[5] = '\0'
55
56 * you should try to avoid ``strncpy``, since it is much slower than
57 ``memcpy`` (it zero-fills the rest of the buffer) and isn't as safe
58 as ``strlcpy``.
59
60 * Use of the functions in this way will reduce the confusion involved
61 in their various behaviors. In other words, this avoids things that
62 look like:
63
64 ::
65
66 strncpy(buf, src, sizeof(buf)-1);
67
68 map_refresh and map_free
69 ------------------------
70
71 * In many cases, it is far more effective to read a file via the
72 operating system's mmap facility than it is to via the traditional
73 ``read()`` and ``lseek`` system calls. To this end, Cyrus provides
74 an operating system independent wrapper around the ``mmap()``
75 services (or lack thereof) of the operating system.
76
77 * Cyrus currently only supports read-only memory maps, all writes back
78 to a file need to be done via the more traditional facilities. This
79 is to enable very low-performance support for operating systems
80 which do not provide an ``mmap()`` facility via a fake userspace
81 ``mmap``.
82
83 * To create a map, simply call ``map_refresh`` on the map (details
84 are in lib/map.h). To free it, call ``map_free`` on the same map.
85
86 * Despite the fact that the maps are read-only, it is often useful
87 to open the file descriptors O_RDWR, especially if the file
88 descriptors could possibly be used for writing elsewhere in the
89 code. Some operating systems REQUIRE file descriptors that are
90 ``mmap()``-ed to be opened O_RDWR, so just do it.
91
92 Network Functions
93 -----------------
94
95 * Cyrus abstracts socket stream access to a concept we refer to as
96 "prot streams" Prot Streams take care of all of the necessary
97 SASL and TLS/SSL encryption that may need to happen before data
98 goes out/comes in from the network. The API is documented in
99 lib/prot.h
100
101 (todo) Authorization Modules
102 ----------------------------
103
104 General Hints
105 -------------
106
107 Some general hints that all made it into my 11/15 16:47 commit that I
108 think may be generally useful to people hacking on the cyrus source:
109
110 * Command line apps should link cli_fatal.o so they all fatal()
111 in the same way, unless there is a really good reason they need to
112 do something unique.
113
114 * If you call ``cyrus_init()`` you must call ``cyrus_done()`` before
115 you exit.
116
117 * No one should ever call ``DB->init()`` or ``DB->done()`` cyrusdb
118 functions except for in ``libcyrus_init()``.
119
120 * I've been trying to keep ``#include`` statements for libcyrus and
121 libimap alphabetical, and below any system includes, but this is
122 merely my personal style
123
124 * Don't exit at the bottom of ``main`` with ``exit(x)`` use
125 ``return`` instead.
126
127 * For all the command line utilities that need to be sure that they
128 are running as the cyrus user, it should be the first thing they
129 do, and they should exit with an appropriate ``fatal()`` call.
130
131 * All services should have a ``shut_down`` call. It should be the
132 ONLY way of exiting the application. ``fatal()`` should always
133 make an attempt to call ``shut_down()`` if it can (though it should
134 have a recursive ``fatal()`` trap just in case). Similarly,
135 command line utilities probably don't need a ``shut_down()``.
136
137
138 Coding Standards
139 ----------------
140
141 These are the generally agreed upon coding standards as thrashed
142 out on the cyrus-devel list in June 2010.
143
144 * Spacing is 4 characters with soft tabs at 8 - mixed tabs and spaces
145 This corresponds to the vi settings `sw=4 sts=4 ts=8` etc.
146
147 * Group the '\*' character with the variable not the type, i.e.
148
149 ::
150
151 char *foo; /* correct */
152 char* foo; /* WRONG */
153
154 * The keywords 'if', 'for', and 'while' take a space after the keyword.
155 The parentheses around the following expression are not closely
156 connected to the expression without any spaces. The ';' inside
157 the 'for' expression have a space after them and not before.
158 For example:
159
160 ::
161
162 if (condition) /* correct */
163 if(condition) /* WRONG */
164 if( condition ) /* WRONG */
165
166 for (i = 0; i < x; i++) /* correct */
167 for(i = 0; i < x; i++) /* WRONG */
168 for (i = 0 ;i < x ;i++) /* WRONG */
169 for(i = 0 ;i < x ;i++) /* WRONG */
170
171 while (foo) /* correct */
172 while(foo) /* WRONG */
173 while( foo ) /* WRONG */
174
175 * Use spaces around the double-character logical operator
176 '||' but don't use spaces around single-character bitwise
177 operator '|'.
178
179 ::
180
181 int flags = FOO|BAR; /* correct */
182 int flags = FOO | BAR; /* WRONG */
183 if (itchy || scratchy) /* correct */
184 if (itchy||scratchy) /* WRONG */
185
186 * Function definitions are followed by a brace on a line by itself,
187 all other braces are inline. Return types are inline with function
188 definition. Old K&R style function definitions are not allowed.
189
190 ::
191
192 void thing(int val) /* correct */
193 { /* correct */
194 ...body...
195 } /* correct */
196
197 void /* WRONG */
198 thing(int val) /* WRONG */
199 { /* WRONG */
200 ...body...
201 } /* WRONG */
202
203 void /* WRONG */
204 thing( /* WRONG */
205 int val) /* WRONG */
206 { /* WRONG */
207 ...body...
208 } /* WRONG */
209
210 void /* WRONG */
211 antique(val) /* WRONG */
212 int val; /* WRONG */
213 { /* WRONG */
214 ...body...
215 } /* WRONG */
216
217 void thing(int val) { /* WRONG */
218 ...body...
219 } /* WRONG */
220
221 void noargs(void) /* correct */
222 { /* correct */
223 ...body...
224 } /* correct */
225
226 void noargs() /* WRONG */
227 { /* WRONG */
228 ...body...
229 } /* WRONG */
230
231
232 * Long argument lists should be split across multiple lines,
233 with the second and subsequent lines indented so that they
234 line up with the start of the first line of arguments.
235
236 ::
237
238 void toomanyargs(int arg1, const char *arg2, /* correct */
239 struct whatever *arg3, int arg4) /* correct */
240 { /* correct */
241 ...body...
242 } /* correct */
243
244 void toomanyargs(int arg1, const char *arg2, /* WRONG */
245 struct whatever *arg3, int arg4) /* WRONG */
246 { /* WRONG */
247 ...body...
248 } /* WRONG */
249
250 void toomanyargs( /* WRONG */
251 int arg1, /* WRONG */
252 const char *arg2, /* WRONG */
253 struct whatever *arg3, /* WRONG */
254 int arg4) /* WRONG */
255 { /* WRONG */
256 ...body...
257 } /* WRONG */
258
259 * Within a function, braces are used in old-fashioned K&R style.
260 Specifically:
261
262 * open braces are placed at the end of the line containing the
263 statement (such as an 'if') to which they belong, after a
264 single space.
265
266 * closing braces are placed on a line by themselves, aligned
267 with the start of the statement to which their matching
268 open brace belongs.
269
270 * this applies even when the closing brace is followed by
271 an 'else' keyword.
272
273 ..
274
275 Yes, it's ugly and hard to read, but you get used to it and
276 most of the code is currently like that. Deal with it.
277
278 ::
279
280 while (cond) { /* correct */
281 ...body... /* correct */
282 } /* correct */
283
284 while (cond){ /* WRONG */
285 ...body... /* WRONG */
286 } /* WRONG */
287
288 while (cond) { ...body... } /* WRONG */
289
290 while (cond) { /* WRONG */
291 ...body... } /* WRONG */
292
293 while (cond) /* WRONG */
294 { /* WRONG */
295 ...body... /* WRONG */
296 } /* WRONG */
297
298 while (cond) /* WRONG */
299 { /* WRONG */
300 ...body... /* WRONG */
301 } /* WRONG */
302
303 if (cond) { /* correct */
304 ...body... /* correct */
305 } /* correct */
306 else if (othercond) { /* correct */
307 ...body... /* correct */
308 } /* correct */
309 else { /* correct */
310 ...body... /* correct */
311 } /* correct */
312
313 if (cond) { /* WRONG */
314 ...body... /* WRONG */
315 } else if (othercond) { /* WRONG */
316 ...body... /* WRONG */
317 } else { /* WRONG */
318 ...body... /* WRONG */
319 } /* WRONG */
320
321 if (cond) /* WRONG */
322 { /* WRONG */
323 ...body... /* WRONG */
324 } /* WRONG */
325 else if (othercond) /* WRONG */
326 { /* WRONG */
327 ...body... /* WRONG */
328 } /* WRONG */
329 else /* WRONG */
330 { /* WRONG */
331 ...body... /* WRONG */
332 } /* WRONG */
333
334 * The braces around a block used in an 'if'...'else if'...'else'
335 may be omitted if the statement is very simple and clear, such
336 as a single function call. This is a judgement call though,
337 so play it safe and use braces.
338
339 ::
340
341 if (cond) /* correct, maybe */
342 function(); /* correct, maybe */
343 else /* correct, maybe */
344 other_function(); /* correct, maybe */
345
346 * The 'goto' keyword needs to be used very very sparingly and only
347 with forethought. The only clearly good example is to goto
348 a label at the end of a function to do cleanup under error
349 conditions.
350
351 ::
352
353 void foo(struct bar *b) /* correct */
354 { /* correct */
355 char *x = xmalloc(...); /* correct */
356
357 if (b == NULL) /* correct */
358 goto error; /* correct */
359
360 if (b->quux != 42) /* correct */
361 goto error; /* correct */
362
363 ...do useful things... /* correct */
364 error: /* correct */
365 free(x); /* correct */
366 } /* correct */
367
368 ..
369
370 Very occasionally, it may be permissable to use 'goto' from within
371 a complicated or multiply-nested loop, to the top of a loop, but
372 only if using another control structure is *less* clear.
373
374 * Generally, zero return is SUCCESS and integer return is an error code.
375
376 * Use "``const char *``" where possible.
377
378 ::
379
380 int is_tacky(const char *name) /* correct */
381 { /* correct */
382 return !strcmp(name, "britney"); /* correct */
383 } /* correct */
384
385 int is_tacky(char *name) /* WRONG */
386 { /* WRONG */
387 return !strcmp(name, "britney"); /* WRONG */
388 } /* WRONG */
389
390 * Use "``struct buf``" for variable length strings where possible.
391
392 * RAII http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization
393 In practice, this means each structure should have a single cleanup
394 function which handles all possible states of the structure and
395 is called whenever the structure needs cleaning up. Likewise,
396 any resources allocated during a function should be cleaned up
397 in the same function, in a single code block at the end of the
398 function (see the comments on 'goto').
399
400 * If you find yourself passing the same multiple parameters through many
401 functions, create a struct and pass around a pointer to that instead.
402
403 * DON'T EVER REUSE THE SAME VARIABLE FOR TWO DIFFERENT PURPOSES IN THE SAME
404 FUNCTION. IN FACT, DON'T REUSE THE SAME VARIABLE _NAME_ FOR DIFFERENT
405 PURPOSES. KTHXBYE. (note: this doesn't apply to 'i', 'n', etc which are
406 used in multiple loops. It applies to using the same name for an absolute
407 offset and a "within this mmap" offset though, and it also applies to
408 using the same variable name for native order and network order numbers,
409 which is where I've seen it a few times and been super frustrated!)
410
411 * Write RFCs in comments capitalized with space after the RFC, like
412 ``RFC 1234``, not like ``rfc 1234`` or ``RFC1234``.