*** /dev/null Sat Nov 23 00:53:44 2024
--- - Sat Nov 23 00:54:11 2024
***************
*** 0 ****
--- 1,220 ----
+ ##
+ ## Copyright (c) 2001-2002 The OSSP Project <http://www.ossp.org/>
+ ## Copyright (c) 2001-2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
+ ##
+ ## This file is part of OSSP ex, an exception library
+ ## which can be found at http://www.ossp.org/pkg/ex/.
+ ##
+ ## This program is free software; you can redistribute it and/or
+ ## modify it under the terms of the GNU General Public License
+ ## as published by the Free Software Foundation; either version
+ ## 2.0 of the License, or (at your option) any later version.
+ ##
+ ## This program is distributed in the hope that it will be useful,
+ ## but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ ## General Public License for more details.
+ ##
+ ## You should have received a copy of the GNU General Public License
+ ## along with this file; if not, write to the Free Software
+ ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+ ## USA, or contact the OSSP project <ossp@ossp.org>.
+ ##
+ ## ex.pod: exception library manual page
+ ##
+
+ =pod
+
+ =head1 NAME
+
+ B<OSSP ex> - Exception Library
+
+ =head1 SYNOPSIS
+
+ B<ex_t> I<variable>;
+
+ B<ex_try> { ... } B<ex_catch> (I<variable>) { ... }
+
+ B<ex_throw>(I<class>, I<object>, I<value>);
+
+ B<ex_rethrow>;
+
+ =head1 DESCRIPTION
+
+ B<OSSP ex> is a small ISO-C++ style exception handling library for use
+ in the ISO-C language. It allows you to use the paradigm of throwing
+ and catching exceptions in order to reduce the amount of error handling
+ code in without making your program less robust. This is achieved
+ by directly transferring exceptional return codes (and the program
+ control flow) from the location where it was raised (throw point) to
+ the location where it is handled (catch point) - usually from a deeply
+ nested sub-routine to a parent routine. All intermediate routines
+ no longer have to make sure that the exceptional return codes from
+ sub-routines are correctly passed back to the parent.
+
+ =head2 EXCEPTIONS
+
+ An exception is a triple E<lt>I<class>,I<object>,I<value>E<gt> where
+ I<class> identifies the class of the exception thrower, I<object>
+ identifies the particular class instance of the exception thrower, and
+ I<value> is the exceptional return code the thrower wants to send to the
+ catcher. All three parts are of type C<void *> internally, but every
+ value can be used which can be (automatically) casted to a C<void *>.
+ Exceptions are created on-the-fly by the B<ex_throw> command.
+
+ =head2 APPLICATION PROGRAMMER INTERFACE (API)
+
+ The B<OSSP ex> API consists of four different elements:
+
+ =over 4
+
+ =item B<ex_t> I<variable>;
+
+ This is the declaration of an exception variable. It is usually never
+ initialized manually. Instead it is initialized by an B<ex_catch> block
+ and just used read-only inside the block. Such a variable of type
+ B<ex_t> consists of six attributes:
+
+ =over 2
+
+ =item C<void *>I<ex_class>
+
+ This is the I<class> argument of the B<ex_throw> call which created
+ the exception. This globally and uniquely identifies the class of
+ I<ex_value>. Usually this is a pointer to a static object (variable,
+ structure or function) which identifies the thrower.
+
+ =item C<void *>I<ex_object>
+
+ This is the I<object> argument of the B<ex_throw> call which created
+ the exception. This globally and uniquely identifies the class instance
+ of I<ex_value> (in case multiple instances exists). Usually this a
+ pointer to a dynamic object (structure) which identifiers the particular
+ instance of the thrower.
+
+ =item C<void *>I<ex_value>
+
+ This is the I<value> argument of the B<ex_throw> call which created the
+ exception. This is the exceptional return code which uniquely identifies
+ the type of exception. Usually this is the value which is C<return>ed
+ if no exceptions would be thrown. In the simple case this is just a
+ numerical return code. In the complex case this can be a pointer to an
+ arbitrary complex data structure describing the exception.
+
+ =item C<char *>I<ex_file>
+
+ This is the file name of the source where the B<ex_throw> call
+ was performed. It is provided as an additional information about
+ the throw point and is intended mainly for tracing and debugging
+ purposes.
+
+ =item C<int> I<ex_line>
+
+ This is the line number inside the source file name where the
+ B<ex_throw> call was performed. It is provided as an additional
+ information about the throw point and is intended mainly for tracing and
+ debugging purposes.
+
+ =item C<char *>I<ex_func>
+
+ This is the function name (if determinable, else "C<#NA#>") inside
+ the source file name where the B<ex_throw> call was performed. It is
+ provided as an additional information about the throw point and is
+ intended mainly for tracing and debugging purposes.
+
+ =back
+
+ =item B<ex_try> { ... } B<ex_catch> (I<variable>) { ... }
+
+ This is the main construct provided by B<OSSP ex>. It is modeled after
+ the ISO-C++ C<try>-C<catch> construct which in turn is very similar to
+ an ISO-C C<if>-C<else> construct. It consists of an B<ex_try> block
+ which forms the dynamic scope of the exception handling (i.e. exceptions
+ thrown there are or from routines called from there are catched) and a
+ B<ex_catch> block where the caught exceptions are handled.
+
+ The B<ex_trx> and B<ex_catch> cannot be used seperately, they work only
+ in combination. In contrast to ISO-C++ there is only one B<ex_catch>
+ block and not multiple ones (all B<OSSP ex> exceptions are of the
+ same ISO-C type B<ex_t>). If an exception is caught, it is stored in
+ I<variable> for inspection (or re-throwing) inside the B<ex_catch>
+ block. Although declared outside, the I<variable> is only valid
+ within the B<ex_catch> block. But it can be re-used in following
+ B<ex_try>/B<ex_catch> constructs, of course.
+
+ The B<ex_try> block is a regular ISO-C language block, but it is not
+ allowed to jump into it via C<goto> or C<longjmp>(3) or out of it via
+ C<return>, C<goto> or C<longjmp>(3) because there is some hidden setup
+ and cleanup that needs to be done by B<OSSP ex> regardless of whether an
+ exception is caught. Jumping into an B<ex_try> clause would avoid doing
+ the setup, and jumping out of it would avoid doing the cleanup. In both
+ cases the result is a broken exception facility.
+
+ The B<ex_catch> block is a regular ISO-C language block without any
+ restrictions.
+
+ =item B<ex_throw>(I<class>, I<object>, I<value>);
+
+ This is second main construct. It builds an exception from the supplied
+ arguments and throws it. If an B<ex_try>/B<ex_catch> clause exists in
+ the dynamic scope of the B<ex_throw> call, this exception is copied into
+ the I<variable> of B<ex_catch> and the program control flow is continued
+ in the B<ex_catch> block. If no B<ex_try>/B<ex_catch> clause exists in
+ the dynamic scope of the B<ex_throw> call, the program C<abort>(3)s. The
+ B<ex_throw> can be performed everywhere, including inside B<ex_try> and
+ B<ex_catch> blocks.
+
+ =item B<ex_rethrow>;
+
+ This is only valid within an B<ex_catch> block and re-throws
+ the current exception (in I<variable>). It is similar to the
+ call B<ex_throw>(I<variable>.ex_class, I<variable>.ex_object,
+ I<variable>.ex_value) but with the difference that the C<ex_file>,
+ C<ex_line> and C<ex_func> elements of the thrown exception are kept.
+
+ =back
+
+ =head1 EXAMPLE
+
+ #include "ex.h"
+
+ ex_t e;
+
+ ex_try {
+ ...
+ ex_throw (..., ..., 123);
+ ...
+ }
+ ex_catch (e) {
+ ...
+ if ((int)e->ex_value == 123)
+ ...
+ else if ((int)e->ex_value == 456)
+ ...
+ else
+ ex_rethrow;
+ ...
+ }
+
+ =head1 SEE ALSO
+
+ C++ try/catch/throw language directives;
+ setjmp(3), longjmp(3), sigsetjmp(3), siglongjmp(3).
+
+ =head1 HISTORY
+
+ B<OSSP ex> was invented in January 2002 by Ralf S. Engelschall for use
+ inside the OSSP project. Its creation was prompted by the requirement to
+ reduce the error handling inside B<OSSP lmtp2nntp>. The implementation
+ is partly derived from B<cexcept> 2.0.0, a similar library written 2000
+ by Adam M. Costello E<lt>amc@cs.berkeley.eduE<gt> and Cosmin Truta
+ E<lt>cosmin@cs.toronto.eduE<gt>.
+
+ =head1 AUTHORS
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+ =cut
+
|
