shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2025-01-10 01:17:44 +03:00
Code

CODING_STYLE: split out section about logging

Browse Source
This commit is contained in:
Lennart Poettering 2019-04-12 16:49:02 +02:00
parent 5638076135
commit 96f6cfbf62
1 changed files with 29 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/CODING_STYLE.md
View File

@ -110,34 +110,6 @@ title: Coding Style
only jump to the end of a function, and little else. Never jump
backwards!
- For every function you add, think about whether it is a "logging"
function or a "non-logging" function. "Logging" functions do logging
on their own, "non-logging" function never log on their own and
expect their callers to log. All functions in "library" code,
i.e. in `src/shared/` and suchlike must be "non-logging". Every time a
"logging" function calls a "non-logging" function, it should log
about the resulting errors. If a "logging" function calls another
"logging" function, then it should not generate log messages, so
that log messages are not generated twice for the same errors.
- If possible, do a combined log & return operation:
```c
r = operation(...);
if (r < 0)
return log_(error|warning|notice|...)_errno(r, "Failed to ...: %m");
```
If the error value is "synthetic", i.e. it was not received from
the called function, use `SYNTHETIC_ERRNO` wrapper to tell the logging
system to not log the errno value, but still return it:
```c
n = read(..., s, sizeof s);
if (n != sizeof s)
return log_error_errno(SYNTHETIC_ERRNO(EIO), "Failed to read ...");
```
- Avoid static variables, except for caches and very few other
cases. Think about thread-safety! While most of our code is never
used in threaded environments, at least the library code should make
@ -351,6 +323,35 @@ title: Coding Style
- When returning a return code from `main()`, please preferably use
`EXIT_FAILURE` and `EXIT_SUCCESS` as defined by libc.
## Logging
- For every function you add, think about whether it is a "logging" function or
a "non-logging" function. "Logging" functions do logging on their own,
"non-logging" function never log on their own and expect their callers to
log. All functions in "library" code, i.e. in `src/shared/` and suchlike must
be "non-logging". Every time a "logging" function calls a "non-logging"
function, it should log about the resulting errors. If a "logging" function
calls another "logging" function, then it should not generate log messages,
so that log messages are not generated twice for the same errors.
- If possible, do a combined log & return operation:
```c
r = operation(...);
if (r < 0)
return log_(error|warning|notice|...)_errno(r, "Failed to ...: %m");
```
If the error value is "synthetic", i.e. it was not received from
the called function, use `SYNTHETIC_ERRNO` wrapper to tell the logging
system to not log the errno value, but still return it:
```c
n = read(..., s, sizeof s);
if (n != sizeof s)
return log_error_errno(SYNTHETIC_ERRNO(EIO), "Failed to read ...");
```
## Memory Allocation
- Always check OOM. There is no excuse. In program code, you can use