doc: document that alloca_safe() and friends are the APIs to use

This commit is contained in:
Lennart Poettering 2021-10-13 14:19:40 +02:00
parent 2f82562bad
commit e3bde91293

View file

@ -365,10 +365,11 @@ SPDX-License-Identifier: LGPL-2.1-or-later
- Avoid fixed-size string buffers, unless you really know the maximum size and
that maximum size is small. It is often nicer to use dynamic memory,
`alloca()` or VLAs. If you do allocate fixed-size strings on the stack, then
it is probably only OK if you either use a maximum size such as `LINE_MAX`,
or count in detail the maximum size a string can have. (`DECIMAL_STR_MAX` and
`DECIMAL_STR_WIDTH` macros are your friends for this!)
`alloca_safe()` or VLAs. If you do allocate fixed-size strings on the stack,
then it is probably only OK if you either use a maximum size such as
`LINE_MAX`, or count in detail the maximum size a string can
have. (`DECIMAL_STR_MAX` and `DECIMAL_STR_WIDTH` macros are your friends for
this!)
Or in other words, if you use `char buf[256]` then you are likely doing
something wrong!
@ -376,13 +377,20 @@ SPDX-License-Identifier: LGPL-2.1-or-later
- Make use of `_cleanup_free_` and friends. It makes your code much nicer to
read (and shorter)!
- Use `alloca()`, but never forget that it is not OK to invoke `alloca()`
within a loop or within function call parameters. `alloca()` memory is
released at the end of a function, and not at the end of a `{}` block. Thus,
if you invoke it in a loop, you keep increasing the stack pointer without
ever releasing memory again. (VLAs have better behavior in this case, so
consider using them as an alternative.) Regarding not using `alloca()`
within function parameters, see the BUGS section of the `alloca(3)` man page.
- Do not use `alloca()`, `strdupa()` or `strndupa()` directly. Use
`alloca_safe()`, `strdupa_safe()` or `strndupa_safe()` instead. (The
difference is that the latter include an assertion that the specified size is
below a safety threshold, so that the program rather aborts than runs into
possible stack overruns.)
- Use `alloca_safe()`, but never forget that it is not OK to invoke
`alloca_safe()` within a loop or within function call
parameters. `alloca_safe()` memory is released at the end of a function, and
not at the end of a `{}` block. Thus, if you invoke it in a loop, you keep
increasing the stack pointer without ever releasing memory again. (VLAs have
better behavior in this case, so consider using them as an alternative.)
Regarding not using `alloca_safe()` within function parameters, see the BUGS
section of the `alloca(3)` man page.
- If you want to concatenate two or more strings, consider using `strjoina()`
or `strjoin()` rather than `asprintf()`, as the latter is a lot slower. This