| 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``. |