Start implementing proper error handling.

[cdecl99.git] / doc / man / libcdecl.3

diff --git a/doc/man/libcdecl.3 b/doc/man/libcdecl.3
index 7b6c791da7df8a50e44b80e80cddfc26a26a41d0..489d7a9ef7eb8fce9a409c70d1aab18735e2efdd 100644 (file)
--- a/doc/man/libcdecl.3
+++ b/doc/man/libcdecl.3
@@ -14,6 +14,8 @@
 .Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl);
 .Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl);
 .Pp
+.Fd const struct cdecl_error *cdecl_get_error(void);
+.Pp
 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);
 .Sh DESCRIPTION
 .Nm
@@ -26,8 +28,33 @@ 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.  The library maintains no global state
-and thus all functions should be safe for use in a multi-threaded environment.
+at least makes an effort to support C99.  The library is thread-safe when
+appropriate facilities exist and are enabled at build time.
+.Sh NAMESPACE
+.Nm
+reserves all identifiers beginning with either
+.Li cdecl_
+or
+.Li CDECL_
+in both the tag and ordinary identifier namespaces.  All external names
+beginning with
+.Li cdecl_
+are reserved, and the library headers may define object-like macros beginning
+with
+.Li CDECL_ .
+The
+.Nm
+library headers may use other identifiers where they do not pollute the global
+namespaces, such as struct members or function parameter names.  Such internal
+identifiers shall not contain any upper-case letters.  As these internal
+identifiers can only conflict with object-like macros, this practice is safe as
+long as the convention of defining object-like macros using upper-case letters
+is adhered to.
+.Pp
+External names beginning with
+.Li cdecl
+followed by two consecutive underscores are not considered part of the ABI and
+are thus subject to change at any time.
 .Sh ABSTRACT SYNTAX TREE
 The functions in
 .Nm
@@ -219,6 +246,44 @@ each function parameter has exactly one full declarator (abstract or
 otherwise).   If
 .Va variadic
 is true, then the function is variadic.
+.Sh ERROR HANDLING
+Some functions in
+.Nm
+can fail.  Such functions will be documented as indicating an error condition
+in a particular way.  It is sometimes necessary to know more about a particular
+error in order to print an informative error message or perform some other
+action.  To facilitate this,
+.Nm
+provides a structure which describes a particular error.
+.Bd -literal -offset indent
+struct cdecl_error {
+       unsigned code;
+       const char *str;
+};
+.Ed
+.Pp
+The
+.Va code
+member identifies the sort of error which has occurred, while the
+.Va str
+member points to a string containing a human-readable description of the error.
+This error information can be retrieved by calling the function
+.Pp
+.Fd const struct cdecl_error *cdecl_get_error(void);
+.Pp
+which returns a pointer to the error structure most recently generated in the
+current thread.  It is therefore thread-safe in that errors occurring in
+another thread will not interfere with the current one.  The returned pointer
+shall remain valid until the next call to any function from
+.Nm
+by the same thread, except that multiple consecutive calls to
+.Va cdecl_get_error
+shall all return the same value.  The same applies to the
+.Va str
+pointer inside the error structure itself.
+.Pp
+If this function is called before an error has been indicated by an earlier
+call in the same thread, the behaviour is undefined.
 .Sh PARSING DECLARATIONS
 To parse a declaration, the function
 .Pp