4 In general the LXC project follows the Linux kernel coding style. However,
5 there are a few differences. They are outlined in this document.
7 The Linux kernel coding style guide can be found within the kernel tree:
9 Documentation/process/coding-style.rst
11 It can be accessed online too:
13 https://www.kernel.org/doc/html/latest/process/coding-style.html
17 - The coding style guide refers to new code. But legacy code can be cleaned up
18 and we are happy to take those patches.
19 - Just because there is still code in LXC that doesn't adhere to the coding
20 standards outlined here does not license not adhering to the coding style. In
21 other words: please stick to the coding style.
22 - Maintainers are free to ignore rules specified here when merging pull
23 requests. This guideline might seem a little weird but it exits to ease new
24 developers into the code base and to prevent unnecessary bikeshedding. If
25 a maintainer feels hat enforcing a specific rule in a given commit would do
26 more harm than good they should always feel free to ignore the rule.
28 Furthermore, when merging pull requests that do not adhere to our coding
29 style maintainers should feel free to grab the commit, adapt it to our coding
30 style and add their Signed-off-by line to it. This is especially helpful to
31 make it easier for first-time contributors and to prevent having pull
32 requests being stuck in the merge queue because of minor details.
33 - We currently do not provide automatic coding style checks but if a suitable
34 tool is found we are happy to integrate it into our test suite. It is
35 possible and recommended to use the `clang-format` binary to check your code.
36 The following options are an approximation of the coding style used here.
37 Simply create a file called `.clang-format` in your home directory with the
40 cat << EOF > "${HOME}"/.clang-format
41 AlignEscapedNewlines: Left
42 BreakBeforeBraces: Attach
43 AlwaysBreakBeforeMultilineStrings: false
44 BreakBeforeBinaryOperators: None
45 MaxEmptyLinesToKeep: 1
46 PenaltyBreakBeforeFirstCallParameter: 1000000
47 BinPackArguments: true
48 BinPackParameters: true
49 AllowAllParametersOfDeclarationOnNextLine: false
50 AlignAfterOpenBracket: true
51 SpacesInSquareBrackets: false
52 SpacesInCStyleCastParentheses: false
53 SpaceInEmptyParentheses: false
54 SpaceBeforeParens: ControlStatements
55 SpaceAfterCStyleCast: false
57 PenaltyReturnTypeOnItsOwnLine: 10000
58 PenaltyExcessCharacter: 10
60 ForEachMacros: ['lxc_list_for_each', 'lxc_list_for_each_safe']
61 AllowShortLoopsOnASingleLine: false
62 AllowShortIfStatementsOnASingleLine: false
63 AllowShortFunctionsOnASingleLine: None
64 AllowShortCaseLabelsOnASingleLine: false
65 AllowShortBlocksOnASingleLine: false
70 BreakBeforeBraces: Linux
71 AllowShortIfStatementsOnASingleLine: false
72 IndentCaseLabels: false
75 However, it will not handle all cases correctly. For example, most `struct`
76 initializations will not be correct. In such cases please refer to the coding
83 ## 3) Only use `/* */` Style Comments
85 - Any comments that are added must use `/* */`.
86 - Single-line comments should start on the same line as the opening `/*`.
87 - Single-line comments should simply be placed between `/* */`. For example:
89 /* Define pivot_root() if missing from the C library */
91 - Mutli-line comment should start on the next line following the opening
92 `/*`and should end with the closing `*/` on a separate line. For
96 * At this point the old-root is mounted on top of our new-root
97 * To unmounted it we must not be chdir()ed into it, so escape back
102 ## 4) Try To Wrap At 80chars
104 - This is not strictly enforced. It is perfectly valid to sometimes
105 overflow this limit if it helps clarity. Nonetheless, try to stick to it
106 and use common sense to decide when not to.
110 - Error messages must start with a capital letter and must **not** end with a
112 - They should be descriptive, without being needlessly long. It is best to just
113 use already existing error messages as examples.
114 - The commit message itself is not subject to rule 4), i.e. it should not be
115 wrapped at 80chars. This is to make it easy to grep for it.
116 - Examples of acceptable error messages are:
118 SYSERROR("Failed to create directory \"%s\"", path);
119 WARN("\"/dev\" directory does not exist. Proceeding without autodev being set up");
124 - Functions that can fail in a non-binary way should return `-1` and set
125 `errno` to a meaningful error code.
126 As a convenience LXC provides the `minus_one_set_errno` macro:
128 static int set_config_net_l2proxy(const char *key, const char *value,
129 struct lxc_conf *lxc_conf, void *data)
131 struct lxc_netdev *netdev = data;
132 unsigned int val = 0;
135 if (lxc_config_value_empty(value))
136 return clr_config_net_l2proxy(key, lxc_conf, data);
139 return minus_one_set_errno(EINVAL);
141 ret = lxc_safe_uint(value, &val);
143 return minus_one_set_errno(-ret);
147 netdev->l2proxy = false;
150 netdev->l2proxy = true;
154 return minus_one_set_errno(EINVAL);
158 ## 7) All Unexported Functions Must Be Declared `static`
160 - Functions which are only used in the current file and are not exported
161 within the codebase need to be declared with the `static` attribute.
163 ## 8) All Exported Functions Must Be Declared `extern` In A Header File
165 - Functions declared in header files (`*.h`) should use the `extern` keyword.
166 - Functions declared in source files (`*.c`) should not use the `extern` keyword.
168 ## 9) Declaring Variables
170 - variables should be declared at the top of the function or at the beginning
171 of a new scope but **never** in the middle of a scope. They should be ordered
172 in the following way:
173 1. automatically freed variables
174 - This specifically references variables cleaned up via the `cleanup`
175 attribute as supported by `gcc` and `clang`.
176 2. initialized variables
177 3. uninitialized variables
179 - put base types before complex types
180 - put standard types defined by libc before types defined by LXC
181 - put multiple declarations of the same type on the same line
182 - Examples of good declarations can be seen in the following function:
184 int lxc_clear_procs(struct lxc_conf *c, const char *key)
186 struct lxc_list *it, *next;
188 const char *k = NULL;
190 if (strcmp(key, "lxc.proc") == 0)
192 else if (strncmp(key, "lxc.proc.", sizeof("lxc.proc.") - 1) == 0)
193 k = key + sizeof("lxc.proc.") - 1;
197 lxc_list_for_each_safe(it, &c->procs, next) {
198 struct lxc_proc *proc = it->elem;
200 if (!all && strcmp(proc->filename, k) != 0)
203 free(proc->filename);
213 ## 10) Functions Not Returning Booleans Must Assign Return Value Before Performing Checks
215 - When checking whether a function not returning booleans was successful or not
216 the returned value must be assigned before it is checked (`str{n}cmp()`
217 functions being one notable exception). For example:
219 /* assign value to "ret" first */
220 ret = mount(sourcepath, cgpath, "cgroup", remount_flags, NULL);
221 /* check whether function was successful */
223 SYSERROR("Failed to remount \"%s\" ro", cgpath);
228 Functions returning booleans can be checked directly. For example:
230 extern bool lxc_string_in_array(const char *needle, const char **haystack);
232 /* check right away */
233 if (lxc_string_in_array("ns", (const char **)h->subsystems))
237 ## 11) Non-Boolean Functions That Behave Like Boolean Functions Must Explicitly Check Against A Value
239 - This rule mainly exists for `str{n}cmp()` type functions. In most cases they
240 are used like a boolean function to check whether a string matches or not.
241 But they return an integer. It is perfectly fine to check `str{n}cmp()`
242 functions directly but you must compare explicitly against a value. That is
243 to say, while they are conceptually boolean functions they shouldn't be
244 treated as such since they don't really behave like boolean functions. So
245 `if (!str{n}cmp())` and `if (str{n}cmp())` checks must not be used. Good
246 examples are found in the following functions:
248 static int set_config_hooks(const char *key, const char *value,
249 struct lxc_conf *lxc_conf, void *data)
253 if (lxc_config_value_empty(value))
254 return lxc_clear_hooks(lxc_conf, key);
256 if (strcmp(key + 4, "hook") == 0) {
257 ERROR("lxc.hook must not have a value");
261 copy = strdup(value);
265 if (strcmp(key + 9, "pre-start") == 0)
266 return add_hook(lxc_conf, LXCHOOK_PRESTART, copy);
267 else if (strcmp(key + 9, "start-host") == 0)
268 return add_hook(lxc_conf, LXCHOOK_START_HOST, copy);
269 else if (strcmp(key + 9, "pre-mount") == 0)
270 return add_hook(lxc_conf, LXCHOOK_PREMOUNT, copy);
271 else if (strcmp(key + 9, "autodev") == 0)
272 return add_hook(lxc_conf, LXCHOOK_AUTODEV, copy);
273 else if (strcmp(key + 9, "mount") == 0)
274 return add_hook(lxc_conf, LXCHOOK_MOUNT, copy);
275 else if (strcmp(key + 9, "start") == 0)
276 return add_hook(lxc_conf, LXCHOOK_START, copy);
277 else if (strcmp(key + 9, "stop") == 0)
278 return add_hook(lxc_conf, LXCHOOK_STOP, copy);
279 else if (strcmp(key + 9, "post-stop") == 0)
280 return add_hook(lxc_conf, LXCHOOK_POSTSTOP, copy);
281 else if (strcmp(key + 9, "clone") == 0)
282 return add_hook(lxc_conf, LXCHOOK_CLONE, copy);
283 else if (strcmp(key + 9, "destroy") == 0)
284 return add_hook(lxc_conf, LXCHOOK_DESTROY, copy);
291 ## 12) Do Not Use C99 Variable Length Arrays (VLA)
293 - They are made optional and there is no guarantee that future C standards
296 ## 13) Use Standard libc Macros When Exiting
298 - libc provides `EXIT_FAILURE` and `EXIT_SUCCESS`. Use them whenever possible
299 in the child of `fork()`ed process or when exiting from a `main()` function.
303 `goto`s are an essential language construct of C and are perfect to perform
304 cleanup operations or simplify the logic of functions. However, here are the
306 - use descriptive `goto` labels.
307 For example, if you know that this label is only used as an error path you
308 should use something like `on_error` instead of `out` as label name.
309 - **only** jump downwards unless you are handling `EAGAIN` errors and want to
310 avoid `do-while` constructs.
311 - An example of a good usage of `goto` is:
313 static int set_config_idmaps(const char *key, const char *value,
314 struct lxc_conf *lxc_conf, void *data)
316 unsigned long hostid, nsid, range;
319 struct lxc_list *idmaplist = NULL;
320 struct id_map *idmap = NULL;
322 if (lxc_config_value_empty(value))
323 return lxc_clear_idmaps(lxc_conf);
325 idmaplist = malloc(sizeof(*idmaplist));
329 idmap = malloc(sizeof(*idmap));
332 memset(idmap, 0, sizeof(*idmap));
334 ret = parse_idmaps(value, &type, &nsid, &hostid, &range);
336 ERROR("Failed to parse id mappings");
340 INFO("Read uid map: type %c nsid %lu hostid %lu range %lu", type, nsid, hostid, range);
342 idmap->idtype = ID_TYPE_UID;
343 else if (type == 'g')
344 idmap->idtype = ID_TYPE_GID;
348 idmap->hostid = hostid;
350 idmap->range = range;
351 idmaplist->elem = idmap;
352 lxc_list_add_tail(&lxc_conf->id_map, idmaplist);
354 if (!lxc_conf->root_nsuid_map && idmap->idtype == ID_TYPE_UID)
355 if (idmap->nsid == 0)
356 lxc_conf->root_nsuid_map = idmap;
359 if (!lxc_conf->root_nsgid_map && idmap->idtype == ID_TYPE_GID)
360 if (idmap->nsid == 0)
361 lxc_conf->root_nsgid_map = idmap;
375 ## 15) Use Booleans instead of integers
377 - When something can be conceptualized in a binary way use a boolean not
380 ## 16) Cleanup Functions Must Handle The Object's Null Type And Being Passed Already Cleaned Up Objects
382 - If you implement a custom cleanup function to e.g. free a complex type
383 you declared you must ensure that the object's null type is handled and
384 treated as a NOOP. For example:
386 void lxc_free_array(void **array, lxc_free_fn element_free_fn)
389 for (p = array; p && *p; p++)
394 - Cleanup functions should also expect to be passed already cleaned up objects.
395 One way to handle this cleanly is to initialize the cleaned up variable to
396 a special value that signals the function that the element has already been
397 freed on the next call. For example, the following function cleans up file
398 descriptors and sets the already closed file descriptors to `-EBADF`. On the
399 next call it can simply check whether the file descriptor is positive and
402 static void lxc_put_attach_clone_payload(struct attach_clone_payload *p)
404 if (p->ipc_socket >= 0) {
405 shutdown(p->ipc_socket, SHUT_RDWR);
406 close(p->ipc_socket);
407 p->ipc_socket = -EBADF;
410 if (p->pty_fd >= 0) {
416 lxc_proc_put_context_info(p->init_ctx);
422 ## 17) Cast to `(void)` When Intentionally Ignoring Return Values
424 - There are cases where you do not care about the return value of a function.
425 Please cast the return value to `(void)` when doing so.
426 - Standard library functions or functions which are known to be ignored by
427 default do not need to be cast to `(void)`. Classical candidates are
428 `close()` and `fclose()`.
431 for (i = 0; hierarchies[i]; i++) {
433 char *path = hierarchies[i]->fullcgpath;
435 ret = chowmod(path, destuid, nsgid, 0755);
439 /* failures to chown() these are inconvenient but not
440 * detrimental we leave these owned by the container launcher,
441 * so that container root can write to the files to attach. we
442 * chmod() them 664 so that container systemd can write to the
443 * files (which systemd in wily insists on doing).
446 if (hierarchies[i]->version == cgroup_super_magic) {
447 fullpath = must_make_path(path, "tasks", null);
448 (void)chowmod(fullpath, destuid, nsgid, 0664);
452 fullpath = must_make_path(path, "cgroup.procs", null);
453 (void)chowmod(fullpath, destuid, 0, 0664);
456 if (hierarchies[i]->version != cgroup2_super_magic)
459 fullpath = must_make_path(path, "cgroup.subtree_control", null);
460 (void)chowmod(fullpath, destuid, nsgid, 0664);
463 fullpath = must_make_path(path, "cgroup.threads", null);
464 (void)chowmod(fullpath, destuid, nsgid, 0664);
469 ## 18) Use `for (;;)` instead of `while (1)` or `while (true)`
471 - Let's be honest, it is really the only sensible way to do this.
473 ## 19) Use The Set Of Supported DCO Statements
475 - Signed-off-by: Random J Developer <random@developer.org>
476 - You did write this code or have the right to contribute it to LXC.
477 - Acked-by: Random J Developer <random@developer.org>
478 - You did read the code and think it is correct. This is usually only used by
479 maintainers or developers that have made significant contributions and can
480 vouch for the correctness of someone else's code.
481 - Reviewed-by: Random J Developer <random@developer.org>
482 - You did review the code and vouch for its correctness, i.e. you'd be
483 prepared to fix bugs it might cause. This is usually only used by
484 maintainers or developers that have made significant contributions and can
485 vouch for the correctness of someone else's code.
486 - Co-developed-by: Random J Developer <random@developer.org>
487 - The code can not be reasonably attributed to a single developer, i.e.
488 you worked on this together.
489 - Tested-by: Random J Developer <random@developer.org>
490 - You verified that the code fixes a given bug or is behaving as advertised.
491 - Reported-by: Random J Developer <random@developer.org>
492 - You found and reported the bug.
493 - Suggested-by: Random J Developer <random@developer.org>
494 - You wrote the code but someone contributed the idea. This line is usually
495 overlooked but it is a sign of good etiquette and coding ethics: if someone
496 helped you solve a problem or had a clever idea do not silently claim it by
497 slapping your Signed-off-by underneath. Be honest and add a Suggested-by.
499 ## 20) Commit Message Outline
501 - You **must** stick to the 80chars limit especially in the title of the commit
503 - Please use English commit messages only.
504 - use meaningful commit messages.
505 - Use correct spelling and grammar.
506 If you are not a native speaker and/or feel yourself struggling with this it
507 is perfectly fine to point this out and there's no need to apologize. Usually
508 developers will be happy to pull your branch and adopt the commit message.
509 - Please always use the affected file (without the file type suffix) or module
510 as a prefix in the commit message.
511 - Examples of good commit messages are:
513 commit b87243830e3b5e95fa31a17cf1bfebe55353bf13
514 Author: Felix Abecassis <fabecassis@nvidia.com>
515 Date: Fri Feb 2 06:19:13 2018 -0800
517 hooks: change the semantic of NVIDIA_VISIBLE_DEVICES=""
519 With LXC, you can override the value of an environment variable to
520 null, but you can't unset an existing variable.
522 The NVIDIA hook was previously activated when NVIDIA_VISIBLE_DEVICES
523 was set to null. As a result, it was not possible to disable the hook
524 by overriding the environment variable in the configuration.
526 The hook can now be disabled by setting NVIDIA_VISIBLE_DEVICES to
527 null or to the new special value "void".
529 Signed-off-by: Felix Abecassis <fabecassis@nvidia.com>
532 commit d6337a5f9dc7311af168aa3d586fdf239f5a10d3
533 Author: Christian Brauner <christian.brauner@ubuntu.com>
534 Date: Wed Jan 31 16:25:11 2018 +0100
536 cgroups: get controllers on the unified hierarchy
538 Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
541 ## 21) Use `_exit()` To Terminate `fork()`ed Child Processes
543 - When `fork()`ing off a child process use `_exit()` to terminate it instead of
544 `exit()`. The `exit()` function is not thread-safe and thus not suited for
545 the shared library which must ensure that it is thread-safe.
547 ## 22) Keep Arrays of `struct`s Aligned Horizontally When Initializing
549 - Arrays of `struct`s are:
557 struct foo_struct new_instance[] = {
563 - Leave a single space after the opening `{` and before closing `}` of the
564 largest member of the last column.
565 - Always leave a single space between the largest member of the current column
566 and the member in the next column.
574 static const struct signame signames[] = {
607 { SIGSTKFLT, "STKFLT" },
622 { SIGVTALRM, "VTALRM" },
628 { SIGWINCH, "WINCH" },
646 { SIGUNUSED, "UNUSED" },
654 ## 23) Use `strlcpy()` instead of `strncpy()`
656 When copying strings always use `strlcpy()` instead of `strncpy()`. The
657 advantage of `strlcpy()` is that it will always append a `\0` byte to the
660 Unless you have a valid reason to accept truncation you must check whether
661 truncation has occurred, treat it as an error, and handle the error
664 ## 24) Use `strlcat()` instead of `strncat()`
666 When concatenating strings always use `strlcat()` instead of `strncat()`. The
667 advantage of `strlcat()` is that it will always append a `\0` byte to the
670 Unless you have a valid reason to accept truncation you must check whether
671 truncation has occurred, treat it as an error, and handle the error
674 ## 25) Use `__fallthrough__` in switch statements
676 If LXC detects that the compiler is new enough it will tell it to check
677 `switch` statements for non-documented fallthroughs. Please always place
678 a `__fallthrough__` after a `case` which falls through the next one.
681 int lxc_attach_run_command(void *payload)
684 lxc_attach_command_t *cmd = payload;
686 ret = execvp(cmd->program, cmd->argv);
698 SYSERROR("Failed to exec \"%s\"", cmd->program);
703 ## 24) Never use `fgets()`
705 LXC does not allow the use of `fgets()`. Use `getline()` or other methods
708 ## 25) Never allocate memory on the stack
710 This specifically forbids any usage of `alloca()` in the codebase.
712 ## 26) Use cleanup macros supported by `gcc` and `clang`
714 LXC has switched from manually cleaning up resources to using cleanup macros
715 supported by `gcc` and `clang`:
717 __attribute__((__cleanup__(<my-cleanup-function-wrapper>)))
719 We do not allow manually cleanups anymore if there are appropriate macros.
720 Currently the following macros are supported:
722 /* close file descriptor */
723 __do_close_prot_errno
725 /* free allocated memory */
726 __do_free __attribute__((__cleanup__(__auto_free__)))
729 __do_fclose __attribute__((__cleanup__(__auto_fclose__)))
732 __do_closedir __attribute__((__cleanup__(__auto_closedir__)))
736 void turn_into_dependent_mounts(void)
738 __do_free char *line = NULL;
739 __do_fclose FILE *f = NULL;
740 __do_close int memfd = -EBADF, mntinfo_fd = -EBADF;
745 mntinfo_fd = open("/proc/self/mountinfo", O_RDONLY | O_CLOEXEC);
746 if (mntinfo_fd < 0) {
747 SYSERROR("Failed to open \"/proc/self/mountinfo\"");
751 memfd = memfd_create(".lxc_mountinfo", MFD_CLOEXEC);
753 char template[] = P_tmpdir "/.lxc_mountinfo_XXXXXX";
755 if (errno != ENOSYS) {
756 SYSERROR("Failed to create temporary in-memory file");
760 memfd = lxc_make_tmpfile(template, true);
762 WARN("Failed to create temporary file");
768 copied = lxc_sendfile_nointr(memfd, mntinfo_fd, NULL, LXC_SENDFILE_MAX);
773 SYSERROR("Failed to copy \"/proc/self/mountinfo\"");
777 ret = lseek(memfd, 0, SEEK_SET);
779 SYSERROR("Failed to reset file descriptor offset");
783 f = fdopen(memfd, "re");
785 SYSERROR("Failed to open copy of \"/proc/self/mountinfo\" to mark all shared. Continuing");
790 * After a successful fdopen() memfd will be closed when calling
791 * fclose(f). Calling close(memfd) afterwards is undefined.
795 while (getline(&line, &len, f) != -1) {
798 target = get_field(line, 4);
802 opts = get_field(target, 2);
806 null_endofword(opts);
807 if (!strstr(opts, "shared"))
810 null_endofword(target);
811 ret = mount(NULL, target, NULL, MS_SLAVE, NULL);
813 SYSERROR("Failed to recursively turn old root mount tree into dependent mount. Continuing...");
816 TRACE("Recursively turned old root mount tree into dependent mount");
818 TRACE("Turned all mount table entries into dependent mount");