From 467f60b780d59c9e062b1cc79117e00b44d1401a Mon Sep 17 00:00:00 2001
From: Andre Maroneze <andre.maroneze@cea.fr>
Date: Tue, 26 Mar 2024 12:33:10 +0100
Subject: [PATCH] [doc] add portability-related macros in userman
---
doc/userman/user-changes.tex | 6 +++++-
doc/userman/user-sources.tex | 30 ++++++++++++++++++++++++++++++
2 files changed, 35 insertions(+), 1 deletion(-)
diff --git a/doc/userman/user-changes.tex b/doc/userman/user-changes.tex
index 6f613040deb..51604605640 100644
--- a/doc/userman/user-changes.tex
+++ b/doc/userman/user-changes.tex
@@ -3,7 +3,11 @@
This chapter summarizes the changes in this documentation between each \FramaC
release. First we list changes of the last release.
-%\section*{Frama-C+dev}
+\section*{Frama-C+dev}
+\begin{itemize}
+\item \textbf{Preparing the Sources:} add subsection on standard library about
+ portability considerations.
+\end{itemize}
\section*{27.0 (Cobalt)}
\begin{itemize}
diff --git a/doc/userman/user-sources.tex b/doc/userman/user-sources.tex
index c85b8d259a1..a30490e6448 100644
--- a/doc/userman/user-sources.tex
+++ b/doc/userman/user-sources.tex
@@ -594,6 +594,36 @@ As stated before, if you want to ensure the code analyzed by \FramaC is
strictly equivalent to the one from the target system, you must either
proofread the definitions, or provide your own library files.
+\subsection*{Portability considerations}
+
+A few POSIX types are specified in an abstract way: {\em not required to be
+ arithmetic types}. This enables them to be defined as e.g. structures.
+Portable code using these types must not inspect them or apply operators
+that are only compatible with arithmetic types (e.g. comparing them with
+\texttt{NULL}). However, such comparisons do exist in the wild, and their
+parsing leads to two issues:
+\begin{itemize}
+\item \FramaC will fail parsing with a generic typing error message;
+\item the user may be unable or unwilling to modify the non-portable code,
+ since they may assume a specific libc implementation that uses an arithmetic
+ type.
+\end{itemize}
+The table below lists a few of such types that currently have special support
+in \FramaC's libc: by adding {\em \#define} macros to the preprocessing
+command-line (e.g. via \texttt{-cpp-extra-args=-D<macro>}), the user can ask
+\FramaC to handle such types as arithmetic.
+
+\begin{table}[!ht]
+ \centering
+ \begin{tabular}{l|l|l}
+ \textbf{Type name} & \textbf{Header} & \textbf{Macro name} \\
+ \midrule
+ \lstinline|pthread_t| & \lstinline|sys/types.h| & \lstinline|__FC_PTHREAD_T_IS_SCALAR| \\
+ \lstinline|fexcept_t| & \lstinline|fenv.h| & \lstinline|__FC_FEXCEPT_T_IS_SCALAR| \\
+ \end{tabular}
+\end{table}
+
+
\section{Warnings during normalization}\label{sec:warnings-normalize}
\emph{Note: the options below are deprecated, replaced by the more general and
--
GitLab