7 - 8ch indent, no tabs, except for files in `man/` which are 2ch indent, and
8 still no tabs, and shell scripts, which are 4ch indent, and no tabs either.
10 - We prefer `/* comments */` over `// comments` in code you commit, please. This
11 way `// comments` are left for developers to use for local, temporary
12 commenting of code for debug purposes (i.e. uncommittable stuff), making such
13 comments easily discernible from explanatory, documenting code comments
14 (i.e. committable stuff).
16 - Don't break code lines too eagerly. We do **not** force line breaks at 80ch,
17 all of today's screens should be much larger than that. But then again, don't
18 overdo it, ~109ch should be enough really. The `.editorconfig`, `.vimrc` and
19 `.dir-locals.el` files contained in the repository will set this limit up for
20 you automatically, if you let them (as well as a few other things). Please
21 note that emacs loads `.dir-locals.el` automatically, but vim needs to be
22 configured to load `.vimrc`, see that file for instructions.
24 - Variables and functions **must** be static, unless they have a
25 prototype, and are supposed to be exported.
27 - structs in `PascalCase` (with exceptions, such as public API structs),
28 variables and functions in `snake_case`.
30 - The destructors always deregister the object from the next bigger
31 object, not the other way around.
33 - To minimize strict aliasing violations, we prefer unions over casting.
35 - For robustness reasons, destructors should be able to destruct
36 half-initialized objects, too.
38 - Error codes are returned as negative `Exxx`. e.g. `return -EINVAL`. There
39 are some exceptions: for constructors, it is OK to return `NULL` on
40 OOM. For lookup functions, `NULL` is fine too for "not found".
42 Be strict with this. When you write a function that can fail due to
43 more than one cause, it *really* should have an `int` as the return value
46 - Do not bother with error checking whether writing to stdout/stderr
49 - Do not log errors from "library" code, only do so from "main
50 program" code. (With one exception: it is OK to log with DEBUG level
51 from any code, with the exception of maybe inner loops).
53 - Always check OOM. There is no excuse. In program code, you can use
54 `log_oom()` for then printing a short message, but not in "library" code.
56 - Do not issue NSS requests (that includes user name and host name
57 lookups) from PID 1 as this might trigger deadlocks when those
58 lookups involve synchronously talking to services that we would need
61 - Do not synchronously talk to any other service from PID 1, due to
64 - Avoid fixed-size string buffers, unless you really know the maximum
65 size and that maximum size is small. They are a source of errors,
66 since they possibly result in truncated strings. It is often nicer
67 to use dynamic memory, `alloca()` or VLAs. If you do allocate fixed-size
68 strings on the stack, then it is probably only OK if you either
69 use a maximum size such as `LINE_MAX`, or count in detail the maximum
70 size a string can have. (`DECIMAL_STR_MAX` and `DECIMAL_STR_WIDTH`
71 macros are your friends for this!)
73 Or in other words, if you use `char buf[256]` then you are likely
74 doing something wrong!
76 - Stay uniform. For example, always use `usec_t` for time
77 values. Do not mix `usec` and `msec`, and `usec` and whatnot.
79 - Make use of `_cleanup_free_` and friends. It makes your code much
80 nicer to read (and shorter)!
82 - Be exceptionally careful when formatting and parsing floating point
83 numbers. Their syntax is locale dependent (i.e. `5.000` in en_US is
84 generally understood as 5, while in de_DE as 5000.).
101 But it is OK if you do not.
103 - Single-line `if` blocks should not be enclosed in `{}`. Use this:
118 - Do not write `foo ()`, write `foo()`.
120 - Please use `streq()` and `strneq()` instead of `strcmp()`, `strncmp()` where
121 applicable (i.e. wherever you just care about equality/inequality, not about
124 - Preferably allocate stack variables on the top of the block:
135 - Unless you allocate an array, `double` is always a better choice
136 than `float`. Processors speak `double` natively anyway, so there is
137 no speed benefit, and on calls like `printf()` `float`s get promoted
138 to `double`s anyway, so there is no point.
140 - Do not mix function invocations with variable definitions in one
161 - Use `goto` for cleaning up, and only use it for that. i.e. you may
162 only jump to the end of a function, and little else. Never jump
165 - Think about the types you use. If a value cannot sensibly be
166 negative, do not use `int`, but use `unsigned`.
168 - Use `char` only for actual characters. Use `uint8_t` or `int8_t`
169 when you actually mean a byte-sized signed or unsigned
170 integers. When referring to a generic byte, we generally prefer the
171 unsigned variant `uint8_t`. Do not use types based on `short`. They
172 *never* make sense. Use `int`, `long`, `long long`, all in
173 unsigned and signed fashion, and the fixed-size types
174 `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `int8_t`, `int16_t`, `int32_t` and so on,
175 as well as `size_t`, but nothing else. Do not use kernel types like
176 `u32` and so on, leave that to the kernel.
178 - Public API calls (i.e. functions exported by our shared libraries)
179 must be marked `_public_` and need to be prefixed with `sd_`. No
180 other functions should be prefixed like that.
182 - In public API calls, you **must** validate all your input arguments for
183 programming error with `assert_return()` and return a sensible return
184 code. In all other calls, it is recommended to check for programming
185 errors with a more brutal `assert()`. We are more forgiving to public
186 users than for ourselves! Note that `assert()` and `assert_return()`
187 really only should be used for detecting programming errors, not for
188 runtime errors. `assert()` and `assert_return()` by usage of `_likely_()`
189 inform the compiler that he should not expect these checks to fail,
190 and they inform fellow programmers about the expected validity and
193 - Never use `strtol()`, `atoi()` and similar calls. Use `safe_atoli()`,
194 `safe_atou32()` and suchlike instead. They are much nicer to use in
195 most cases and correctly check for parsing errors.
197 - For every function you add, think about whether it is a "logging"
198 function or a "non-logging" function. "Logging" functions do logging
199 on their own, "non-logging" function never log on their own and
200 expect their callers to log. All functions in "library" code,
201 i.e. in `src/shared/` and suchlike must be "non-logging". Every time a
202 "logging" function calls a "non-logging" function, it should log
203 about the resulting errors. If a "logging" function calls another
204 "logging" function, then it should not generate log messages, so
205 that log messages are not generated twice for the same errors.
207 - If possible, do a combined log & return operation:
212 return log_(error|warning|notice|...)_errno(r, "Failed to ...: %m");
215 If the error value is "synthetic", i.e. it was not received from
216 the called function, use `SYNTHETIC_ERRNO` wrapper to tell the logging
217 system to not log the errno value, but still return it:
220 n = read(..., s, sizeof s);
222 return log_error_errno(SYNTHETIC_ERRNO(EIO), "Failed to read ...");
225 - Avoid static variables, except for caches and very few other
226 cases. Think about thread-safety! While most of our code is never
227 used in threaded environments, at least the library code should make
228 sure it works correctly in them. Instead of doing a lot of locking
229 for that, we tend to prefer using TLS to do per-thread caching (which
230 only works for small, fixed-size cache objects), or we disable
231 caching for any thread that is not the main thread. Use
232 `is_main_thread()` to detect whether the calling thread is the main
235 - Command line option parsing:
236 - Do not print full `help()` on error, be specific about the error.
237 - Do not print messages to stdout on error.
238 - Do not POSIX_ME_HARDER unless necessary, i.e. avoid `+` in option string.
240 - Do not write functions that clobber call-by-reference variables on
241 failure. Use temporary variables for these cases and change the
242 passed in variables only on success.
244 - When you allocate a file descriptor, it should be made `O_CLOEXEC`
245 right from the beginning, as none of our files should leak to forked
246 binaries by default. Hence, whenever you open a file, `O_CLOEXEC` must
247 be specified, right from the beginning. This also applies to
248 sockets. Effectively, this means that all invocations to:
250 - `open()` must get `O_CLOEXEC` passed,
251 - `socket()` and `socketpair()` must get `SOCK_CLOEXEC` passed,
252 - `recvmsg()` must get `MSG_CMSG_CLOEXEC` set,
253 - `F_DUPFD_CLOEXEC` should be used instead of `F_DUPFD`, and so on,
254 - invocations of `fopen()` should take `e`.
256 - We never use the POSIX version of `basename()` (which glibc defines it in
257 `libgen.h`), only the GNU version (which glibc defines in `string.h`).
258 The only reason to include `libgen.h` is because `dirname()`
259 is needed. Every time you need that please immediately undefine
260 `basename()`, and add a comment about it, so that no code ever ends up
261 using the POSIX version!
263 - Use the bool type for booleans, not integers. One exception: in public
264 headers (i.e those in `src/systemd/sd-*.h`) use integers after all, as `bool`
265 is C99 and in our public APIs we try to stick to C89 (with a few extension).
267 - When you invoke certain calls like `unlink()`, or `mkdir_p()` and you
268 know it is safe to ignore the error it might return (because a later
269 call would detect the failure anyway, or because the error is in an
270 error path and you thus couldn't do anything about it anyway), then
271 make this clear by casting the invocation explicitly to `(void)`. Code
272 checks like Coverity understand that, and will not complain about
273 ignored error codes. Hence, please use this:
276 (void) unlink("/foo/bar/baz");
279 instead of just this:
282 unlink("/foo/bar/baz");
285 Don't cast function calls to `(void)` that return no error
286 conditions. Specifically, the various `xyz_unref()` calls that return a `NULL`
287 object shouldn't be cast to `(void)`, since not using the return value does not
290 - Don't invoke `exit()`, ever. It is not replacement for proper error
291 handling. Please escalate errors up your call chain, and use normal
292 `return` to exit from the main function of a process. If you
293 `fork()`ed off a child process, please use `_exit()` instead of `exit()`,
294 so that the exit handlers are not run.
296 - Please never use `dup()`. Use `fcntl(fd, F_DUPFD_CLOEXEC, 3)`
297 instead. For two reason: first, you want `O_CLOEXEC` set on the new `fd`
298 (see above). Second, `dup()` will happily duplicate your `fd` as 0, 1,
299 2, i.e. stdin, stdout, stderr, should those `fd`s be closed. Given the
300 special semantics of those `fd`s, it's probably a good idea to avoid
301 them. `F_DUPFD_CLOEXEC` with `3` as parameter avoids them.
303 - When you define a destructor or `unref()` call for an object, please
304 accept a `NULL` object and simply treat this as NOP. This is similar
305 to how libc `free()` works, which accepts `NULL` pointers and becomes a
306 NOP for them. By following this scheme a lot of `if` checks can be
307 removed before invoking your destructor, which makes the code
308 substantially more readable and robust.
310 - Related to this: when you define a destructor or `unref()` call for an
311 object, please make it return the same type it takes and always
312 return `NULL` from it. This allows writing code like this:
318 which will always work regardless if `p` is initialized or not, and
319 guarantees that `p` is `NULL` afterwards, all in just one line.
321 - Use `alloca()`, but never forget that it is not OK to invoke `alloca()`
322 within a loop or within function call parameters. `alloca()` memory is
323 released at the end of a function, and not at the end of a `{}`
324 block. Thus, if you invoke it in a loop, you keep increasing the
325 stack pointer without ever releasing memory again. (VLAs have better
326 behavior in this case, so consider using them as an alternative.)
327 Regarding not using `alloca()` within function parameters, see the
328 BUGS section of the `alloca(3)` man page.
330 - Use `memzero()` or even better `zero()` instead of `memset(..., 0, ...)`
332 - Instead of using `memzero()`/`memset()` to initialize structs allocated
333 on the stack, please try to use c99 structure initializers. It's
334 short, prettier and actually even faster at execution. Hence:
352 - When returning a return code from `main()`, please preferably use
353 `EXIT_FAILURE` and `EXIT_SUCCESS` as defined by libc.
355 - The order in which header files are included doesn't matter too
356 much. systemd-internal headers must not rely on an include order, so
357 it is safe to include them in any order possible.
358 However, to not clutter global includes, and to make sure internal
359 definitions will not affect global headers, please always include the
360 headers of external components first (these are all headers enclosed
361 in <>), followed by our own exported headers (usually everything
362 that's prefixed by `sd-`), and then followed by internal headers.
363 Furthermore, in all three groups, order all includes alphabetically
364 so duplicate includes can easily be detected.
366 - To implement an endless loop, use `for (;;)` rather than `while (1)`.
367 The latter is a bit ugly anyway, since you probably really
368 meant `while (true)`. To avoid the discussion what the right
369 always-true expression for an infinite while loop is, our
370 recommendation is to simply write it without any such expression by
373 - Never use the `off_t` type, and particularly avoid it in public
374 APIs. It's really weirdly defined, as it usually is 64-bit and we
375 don't support it any other way, but it could in theory also be
376 32-bit. Which one it is depends on a compiler switch chosen by the
377 compiled program, which hence corrupts APIs using it unless they can
378 also follow the program's choice. Moreover, in systemd we should
379 parse values the same way on all architectures and cannot expose
380 `off_t` values over D-Bus. To avoid any confusion regarding conversion
381 and ABIs, always use simply `uint64_t` directly.
383 - Commit message subject lines should be prefixed with an appropriate
384 component name of some kind. For example "journal: ", "nspawn: " and
387 - Do not use "Signed-Off-By:" in your commit messages. That's a kernel
388 thing we don't do in the systemd project.
390 - Avoid leaving long-running child processes around, i.e. `fork()`s that
391 are not followed quickly by an `execv()` in the child. Resource
392 management is unclear in this case, and memory CoW will result in
393 unexpected penalties in the parent much, much later on.
395 - Don't block execution for arbitrary amounts of time using `usleep()`
396 or a similar call, unless you really know what you do. Just "giving
397 something some time", or so is a lazy excuse. Always wait for the
398 proper event, instead of doing time-based poll loops.
400 - To determine the length of a constant string `"foo"`, don't bother with
401 `sizeof("foo")-1`, please use `strlen()` instead (both gcc and clang optimize
402 the call away for fixed strings). The only exception is when declaring an
403 array. In that case use STRLEN, which evaluates to a static constant and
404 doesn't force the compiler to create a VLA.
406 - If you want to concatenate two or more strings, consider using `strjoina()`
407 or `strjoin()` rather than `asprintf()`, as the latter is a lot slower. This
408 matters particularly in inner loops (but note that `strjoina()` cannot be
411 - Please avoid using global variables as much as you can. And if you
412 do use them make sure they are static at least, instead of
413 exported. Especially in library-like code it is important to avoid
414 global variables. Why are global variables bad? They usually hinder
415 generic reusability of code (since they break in threaded programs,
416 and usually would require locking there), and as the code using them
417 has side-effects make programs non-transparent. That said, there are
418 many cases where they explicitly make a lot of sense, and are OK to
419 use. For example, the log level and target in `log.c` is stored in a
420 global variable, and that's OK and probably expected by most. Also
421 in many cases we cache data in global variables. If you add more
422 caches like this, please be careful however, and think about
423 threading. Only use static variables if you are sure that
424 thread-safety doesn't matter in your case. Alternatively, consider
425 using TLS, which is pretty easy to use with gcc's `thread_local`
426 concept. It's also OK to store data that is inherently global in
427 global variables, for example data parsed from command lines, see
430 - If you parse a command line, and want to store the parsed parameters
431 in global variables, please consider prefixing their names with
432 `arg_`. We have been following this naming rule in most of our
433 tools, and we should continue to do so, as it makes it easy to
434 identify command line parameter variables, and makes it clear why it
435 is OK that they are global variables.
437 - When exposing public C APIs, be careful what function parameters you make
438 `const`. For example, a parameter taking a context object should probably not
439 be `const`, even if you are writing an otherwise read-only accessor function
440 for it. The reason is that making it `const` fixates the contract that your
441 call won't alter the object ever, as part of the API. However, that's often
442 quite a promise, given that this even prohibits object-internal caching or
443 lazy initialization of object variables. Moreover, it's usually not too useful
444 for client applications. Hence, please be careful and avoid `const` on object
445 parameters, unless you are very sure `const` is appropriate.
447 - Make sure to enforce limits on every user controllable resource. If the user
448 can allocate resources in your code, your code must enforce some form of
449 limits after which it will refuse operation. It's fine if it is hard-coded (at
450 least initially), but it needs to be there. This is particularly important
451 for objects that unprivileged users may allocate, but also matters for
452 everything else any user may allocated.
454 - `htonl()`/`ntohl()` and `htons()`/`ntohs()` are weird. Please use `htobe32()` and
455 `htobe16()` instead, it's much more descriptive, and actually says what really
456 is happening, after all `htonl()` and `htons()` don't operate on `long`s and
457 `short`s as their name would suggest, but on `uint32_t` and `uint16_t`. Also,
458 "network byte order" is just a weird name for "big endian", hence we might
459 want to call it "big endian" right-away.
461 - You might wonder what kind of common code belongs in `src/shared/` and what
462 belongs in `src/basic/`. The split is like this: anything that is used to
463 implement the public shared object we provide (sd-bus, sd-login, sd-id128,
464 nss-systemd, nss-mymachines, nss-resolve, nss-myhostname, pam_systemd), must
465 be located in `src/basic` (those objects are not allowed to link to
466 libsystemd-shared.so). Conversely, anything which is shared between multiple
467 components and does not need to be in `src/basic/`, should be in
473 - may be used by all code in the tree
474 - may not use any code outside of `src/basic/`
477 - may be used by all code in the tree, except for code in `src/basic/`
478 - may not use any code outside of `src/basic/`, `src/libsystemd/`
481 - may be used by all code in the tree, except for code in `src/basic/`,
482 `src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under
483 `src/journal/` that end up in `libjournal-client.a` convenience library.
484 - may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/`
486 - Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
487 incompatible with glibc it's on them. However, if there are equivalent POSIX
488 and Linux/GNU-specific APIs, we generally prefer the POSIX APIs. If there
489 aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
490 implementations of libc to catch up with glibc.
492 - Whenever installing a signal handler, make sure to set `SA_RESTART` for it, so
493 that interrupted system calls are automatically restarted, and we minimize
494 hassles with handling `EINTR` (in particular as `EINTR` handling is pretty broken
497 - When applying C-style unescaping as well as specifier expansion on the same
498 string, always apply the C-style unescaping fist, followed by the specifier
499 expansion. When doing the reverse, make sure to escape `%` in specifier-style
500 first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
502 - It's a good idea to use `O_NONBLOCK` when opening 'foreign' regular files, i.e.
503 file system objects that are supposed to be regular files whose paths where
504 specified by the user and hence might actually refer to other types of file
505 system objects. This is a good idea so that we don't end up blocking on
506 'strange' file nodes, for example if the user pointed us to a FIFO or device
507 node which may block when opening. Moreover even for actual regular files
508 `O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
509 effect on the regular file. If in doubt consider turning off `O_NONBLOCK` again
512 - When referring to a configuration file option in the documentation and such,
513 please always suffix it with `=`, to indicate that it is a configuration file
516 - When referring to a command line option in the documentation and such, please
517 always prefix with `--` or `-` (as appropriate), to indicate that it is a
520 - When referring to a file system path that is a directory, please always
521 suffix it with `/`, to indicate that it is a directory, not a regular file
522 (or other file system object).
524 - Don't use `fgets()`, it's too hard to properly handle errors such as overly
525 long lines. Use `read_line()` instead, which is our own function that handles