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 file descriptors

Browse Source
This commit is contained in:
Lennart Poettering 2019-04-12 16:34:01 +02:00
parent 0485824030
commit 25553cd9cd
1 changed files with 24 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/CODING_STYLE.md
View File

@ -196,19 +196,6 @@ title: Coding Style
failure. Use temporary variables for these cases and change the
passed in variables only on success.
- When you allocate a file descriptor, it should be made `O_CLOEXEC`
right from the beginning, as none of our files should leak to forked
binaries by default. Hence, whenever you open a file, `O_CLOEXEC` must
be specified, right from the beginning. This also applies to
sockets. Effectively, this means that all invocations to:
- `open()` must get `O_CLOEXEC` passed,
- `socket()` and `socketpair()` must get `SOCK_CLOEXEC` passed,
- `recvmsg()` must get `MSG_CMSG_CLOEXEC` set,
- `F_DUPFD_CLOEXEC` should be used instead of `F_DUPFD`, and so on,
- invocations of `fopen()` should take `e`.
- When you invoke certain calls like `unlink()`, or `mkdir_p()` and you
know it is safe to ignore the error it might return (because a later
call would detect the failure anyway, or because the error is in an
@ -398,16 +385,6 @@ title: Coding Style
expansion. When doing the reverse, make sure to escape `%` in specifier-style
first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
- It's a good idea to use `O_NONBLOCK` when opening 'foreign' regular files, i.e.
file system objects that are supposed to be regular files whose paths where
specified by the user and hence might actually refer to other types of file
system objects. This is a good idea so that we don't end up blocking on
'strange' file nodes, for example if the user pointed us to a FIFO or device
node which may block when opening. Moreover even for actual regular files
`O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
effect on the regular file. If in doubt consider turning off `O_NONBLOCK` again
after opening.
## Memory Allocation
- Always check OOM. There is no excuse. In program code, you can use
@ -475,6 +452,30 @@ title: Coding Style
headers (i.e those in `src/systemd/sd-*.h`) use integers after all, as `bool`
is C99 and in our public APIs we try to stick to C89 (with a few extension).
## File Descriptors
- When you allocate a file descriptor, it should be made `O_CLOEXEC` right from
the beginning, as none of our files should leak to forked binaries by
default. Hence, whenever you open a file, `O_CLOEXEC` must be specified,
right from the beginning. This also applies to sockets. Effectively, this
means that all invocations to:
- `open()` must get `O_CLOEXEC` passed,
- `socket()` and `socketpair()` must get `SOCK_CLOEXEC` passed,
- `recvmsg()` must get `MSG_CMSG_CLOEXEC` set,
- `F_DUPFD_CLOEXEC` should be used instead of `F_DUPFD`, and so on,
- invocations of `fopen()` should take `e`.
- It's a good idea to use `O_NONBLOCK` when opening 'foreign' regular files,
i.e. file system objects that are supposed to be regular files whose paths
where specified by the user and hence might actually refer to other types of
file system objects. This is a good idea so that we don't end up blocking on
'strange' file nodes, for example if the user pointed us to a FIFO or device
node which may block when opening. Moreover even for actual regular files
`O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
effect on the regular file. If in doubt consider turning off `O_NONBLOCK`
again after opening.
## Referencing Concepts
- When referring to a configuration file option in the documentation and such,