From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 13 Oct 2021 12:19:40 +0000 (+0200)
Subject: doc: document that alloca_safe() and friends are the APIs to use
X-Git-Tag: v250-rc1~504^2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e3bde91293df336c8839a1a7a79ed50f954150db;p=thirdparty%2Fsystemd.git

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

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index b3c197250a1..f2c877ccebf 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -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