From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 25 Apr 2023 11:56:20 +0000 (+0200)
Subject: doc: say in CODING_STYLE that AT_EMPTY_PATH should be implied on openat() style APIs... 
X-Git-Tag: v254-rc1~642
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4d26b2277a9a982b8c061d7da2300b266161b716;p=thirdparty%2Fsystemd.git

doc: say in CODING_STYLE that AT_EMPTY_PATH should be implied on openat() style APIs (and NULL path is OK)

As discussed here:

https://github.com/systemd/systemd/pull/27397#issuecomment-1521630044
---

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index 1a044c023ac..f76525205fd 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -613,6 +613,15 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   effect on the regular file. If in doubt consider turning off `O_NONBLOCK`
   again after opening.
 
+- These days we generally prefer `openat()`-style file APIs, i.e. APIs that
+  accept a combination of file descriptor and path string, and where the path
+  (if not absolute) is considered relative to the specified file
+  descriptor. When implementing library calls in similar style, please make
+  sure to imply `AT_EMPTY_PATH` if an empty or `NULL` path argument is
+  specified (and convert that latter to an empty string). This differs from the
+  underlying kernel semantics, where `AT_EMPTY_PATH` must always be specified
+  explicitly, and `NULL` is not acepted as path.
+
 ## Command Line
 
 - If you parse a command line, and want to store the parsed parameters in