argument consists of a sequence of calls to the keyword-argument macros
described below, one after another without any separation.
- In C89, macro actual arguments are not permitted to be empty; if there are
- no keyword arguments to provide, and you're using a C89 compiler, then use
- @|NO_KWARGS| (below) instead. If your compiler supports C99 or later, it's
- fine to just write @|KWARGS()| instead.
+ If there are no keyword arguments, use @|NO_KWARGS| (below) instead.
\end{describe}
\begin{describe}{mac}{NO_KWARGS}
A marker, to be written instead of a @|KWARGS| invocation, to indicate that
no keyword arguments are to be passed to a function.
- This is unnecessary with compilers which support C99 or later, since once
- can use @|KWARGS()| with an empty @<body> argument.
+ Using this macro instead of @|KWARGS| if there are no arguments does two
+ things:
+ \begin{itemize}
+
+ \item C89 doesn't permit empty macro arguments for some reason, so
+ @|NO_KWARGS| is necessary when using a C89 compiler.
+
+ \item Omitting the null terminator is a common mistake, so @|<keyword.h>|
+ tries to get the compiler to warn if you miss it. However, the
+ \descref{KWTAIL}[macro]{mac} introduces an extra real argument
+ @|kwfirst_|, because it's not possible to scan a variable-length argument
+ tail if there are no mandatory arguments. If you use @|KWARGS()|, with
+ an empty argument list, then the null terminator is passed as @|kwfirst_|
+ and the variable-length tail ends up empty, which might trigger a
+ compiler warning about the missing terminator. @|NO_KWARGS| passes
+ \emph{two} null terminators: a real one to indicate that there are no
+ keyword arguments, and a dummy one to placate the compiler.
+
+ (Sod method entry functions don't have this extra argument, so
+ @|KWARGS()| would work fine for sending Sod messages with keyword
+ arguments if you're using C99 or later, but it's probably best to use the
+ version which always works.)
+
+ \end{itemize}
\end{describe}
The following keyword-argument macros can be used within the @|KWARGS|