Don't run configure tests for threading if disabled.

[cdecl99.git] / doc / libcdecl.3

diff --git a/doc/libcdecl.3 b/doc/libcdecl.3
index 0d17d2b739f368cb964b05c0dca2780ab3d74f3e..725566b2944fa8bbfcf2b9dc02460b820e4a8672 100644 (file)
--- a/doc/libcdecl.3
+++ b/doc/libcdecl.3
@@ -1,6 +1,6 @@
-.Dd July 27, 2023
-.Os cdecl99
+.Dd January 17, 2024

 .Dt LIBCDECL \&3 "Cdecl99 Developer's Manual"
 .Dt LIBCDECL \&3 "Cdecl99 Developer's Manual"

+.Os cdecl99

 .Sh NAME
 .Nm libcdecl
 .Nd C library for making sense of C declarations
 .Sh NAME
 .Nm libcdecl
 .Nd C library for making sense of C declarations


@@ -17,7 +17,7 @@
 .Fd const struct cdecl_error *cdecl_get_error(void);
 .Pp
 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);
 .Fd const struct cdecl_error *cdecl_get_error(void);
 .Pp
 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);

-.Fd bool cdecl_is_abstract(struct cdecl_declarator *declarator);
+.Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);

 .Sh DESCRIPTION
 .Nm
 provides support for parsing C declarations and translating them to something
 .Sh DESCRIPTION
 .Nm
 provides support for parsing C declarations and translating them to something


@@ -29,8 +29,7 @@ see the
 manual page.
 .Pp
 .Nm
 manual page.
 .Pp
 .Nm

-is intended to be portable to any system with a working C implementation that
-at least makes an effort to support C99.
+is intended to be portable to any system with a standard C compiler.

 The library is thread-safe when appropriate facilities exist and are enabled at
 build time.
 .Sh NAMESPACE
 The library is thread-safe when appropriate facilities exist and are enabled at
 build time.
 .Sh NAMESPACE


@@ -230,7 +229,7 @@ union member points to the C string containing the identifier.
 Since a null declarator may be deeply nested in the declarator chain, the
 function
 .Pp
 Since a null declarator may be deeply nested in the declarator chain, the
 function
 .Pp

-.Fd bool cdecl_is_abstract(struct cdecl_declarator *declarator);
+.Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);

 .Pp
 can be used to determine whether or not a given declarator declares an
 identifier.
 .Pp
 can be used to determine whether or not a given declarator declares an
 identifier.


@@ -248,9 +247,10 @@ member is non-null, then it points to the first element of a singly-linked list
 of type qualifiers.
 .Ss Array Declarators
 .Bd -literal -offset indent
 of type qualifiers.
 .Ss Array Declarators
 .Bd -literal -offset indent

+typedef unsigned long long cdecl_uintmax; /* depends on configuration */

 struct cdecl_array {
        char *vla;
 struct cdecl_array {
        char *vla;

-       uintmax_t length;
+       cdecl_uintmax length;

 };
 .Ed
 .Pp
 };
 .Ed
 .Pp


@@ -265,17 +265,32 @@ Otherwise, if
 .Va length
 is positive, then this is an array declarator with the specified length.
 Otherwise, this is an incomplete array declarator.
 .Va length
 is positive, then this is an array declarator with the specified length.
 Otherwise, this is an incomplete array declarator.

+.Pp
+If the library was configured using a compiler which does not support
+.Vt unsigned long long ,
+then the
+.Vt cdecl_uintmax
+type is defined as
+.Vt unsigned long
+instead.
+Prior versions of
+.Nm
+used
+.Vt uintmax_t
+directly.

 .Ss Function Declarators
 .Bd -literal -offset indent
 .Ss Function Declarators
 .Bd -literal -offset indent

+typedef _Bool cdecl_bool; /* depends on configuration */

 struct cdecl_function {
        struct cdecl *parameters;
 struct cdecl_function {
        struct cdecl *parameters;

-       _Bool variadic;
+       cdecl_bool variadic;

 };
 .Ed
 .Pp
 If
 .Va parameters
 };
 .Ed
 .Pp
 If
 .Va parameters

-is null, then this is a non-prototype function declarator.
+is null, then this is a non-prototype function declarator with an empty
+identifier list.

 Otherwise,
 .Va parameters
 points to the first element of a singly-linked list of declarations
 Otherwise,
 .Va parameters
 points to the first element of a singly-linked list of declarations


@@ -284,15 +299,27 @@ Note that, unlike toplevel declarations, each function parameter has exactly
 one full declarator (abstract or otherwise).
 If
 .Va variadic
 one full declarator (abstract or otherwise).
 If
 .Va variadic

-is true, then the function is variadic.
+is non-zero, then the function is variadic.
+.Pp
+Please note that if the compiler used to build the library does not support
+.Vt _Bool ,
+then
+.Vt cdecl_bool
+will be defined as
+.Vt signed char
+instead.
+In most cases these will have a compatible binary representation, provided
+that applications do not set
+.Va variadic
+to any values besides 0 or 1.

 .Pp
 .Pp

-Note that old-style function declarations with non-empty identifier lists are
-not directly represented here: this is because they are syntactically identical
-to a prototype where every parameter is a typedef name.
-Since
+Old-style function declarations with non-empty identifier lists cannot be
+directly represented by this structure.
+Such declarations are syntactically identical to a prototype with every
+parameter consisting solely of a typedef name.

 .Nm
 .Nm

-isn't a C compiler, there is no way for its parser to tell these two kinds of
-declarations apart.
+cannot tell these apart when parsing and thus will return a parameter
+list, which can be rendered as expected.

 .Sh ERROR HANDLING
 Some functions in
 .Nm
 .Sh ERROR HANDLING
 Some functions in
 .Nm


@@ -425,7 +452,7 @@ is non-zero, the resulting string is '\\0' terminated even if it was truncated.
 .Sh AUTHORS
 Nick Bowler <nbowler@draconx.ca>
 .Sh COPYRIGHT
 .Sh AUTHORS
 Nick Bowler <nbowler@draconx.ca>
 .Sh COPYRIGHT

-Copyright \(co 2011\(en2012, 2021, 2023 Nick Bowler
+Copyright \(co 2011\(en2012, 2021, 2023\(en2024 Nick Bowler

 .Pp
 Permission is granted to copy, distribute and/or modify this manual under the
 terms of the GNU General Public License as published by the Free Software
 .Pp
 Permission is granted to copy, distribute and/or modify this manual under the
 terms of the GNU General Public License as published by the Free Software