From: Alejandro Colomar <alx@kernel.org>
Date: Fri, 13 Mar 2026 00:53:38 +0000 (+0100)
Subject: lib/io/README: Add file
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=91633beae37f6c166f14f89bb81b59941da56845;p=thirdparty%2Fshadow.git

lib/io/README: Add file

This documents the main APIs under 'lib/io/'.

Reviewed-by: Iker Pedrosa <ipedrosa@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/lib/io/README b/lib/io/README
new file mode 100644
index 000000000..adae56beb
--- /dev/null
+++ b/lib/io/README
@@ -0,0 +1,29 @@
+General guidelines:
+===================
+
+-  If there's a *_a() macro that wraps an API, use the macro if
+   possible.  These use countof() to add bounds safety.
+
+-  If there's a *_T() macro that wraps an API, use the macro if
+   possible.  These use _Generic() to add type safety.
+   Prefer *_a() macros over *_T() macros.
+
+-  If there's an upper-case macro that wraps a function, use the macro
+   if possible.  These use macro magic to add safety.
+   Prefer *_T() macros over upper-case macros.
+
+
+Specific guidelines:
+====================
+	Under lib/io/ we provide a set of APIs to do IO.
+	In this section, we provide a broad overview.
+
+fgets/ - Read lines
+
+    fgets_a()
+	Like fgets(3), but takes an array.
+
+syslog.h - System log
+
+    SYSLOG()
+	Like syslog(3), but uses the C locale if necessary.