www.delorie.com/gnu/docs/recode/recode_17.html

search

	Buy GNU books!

The recode reference manual

4.1 Outer level functions

The outer level functions mainly prepare the whole recoding library for use, or do actions which are unrelated to specific recodings. Here is an example of a program which does not really make anything useful.

#include <stdbool.h> #include <recode.h> const char *program_name; int main (int argc, char *const *argv) { program_name = argv[0]; RECODE_OUTER outer = recode_new_outer (true); recode_delete_outer (outer); exit (0); }

The header file <recode.h> declares an opaque RECODE_OUTER structure, which the programmer should use for allocating a variable in his program (let's assume the programmer is a male, here, no prejudice intended). This `outer' variable is given as a first argument to all outer level functions.

The <recode.h> header file uses the Boolean type setup by the system header file <stdbool.h>. But this header file is still fairly new in C standards, and likely does not exist everywhere. If you system does not offer this system header file yet, the proper compilation of the <recode.h> file could be guaranteed through the replacement of the inclusion line by:

typedef enum {false = 0, true = 1} bool;

People wanting wider portability, or Autoconf lovers, might arrange their `configure.in' for being able to write something more general, like:

#if STDC_HEADERS # include <stdlib.h> #endif /* Some systems do not define EXIT_*, even with STDC_HEADERS. */ #ifndef EXIT_SUCCESS # define EXIT_SUCCESS 0 #endif #ifndef EXIT_FAILURE # define EXIT_FAILURE 1 #endif /* The following test is to work around the gross typo in systems like Sony NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1. */ #if !EXIT_FAILURE # undef EXIT_FAILURE # define EXIT_FAILURE 1 #endif #if HAVE_STDBOOL_H # include <stdbool.h> #else typedef enum {false = 0, true = 1} bool; #endif #include <recode.h> const char *program_name; int main (int argc, char *const *argv) { program_name = argv[0]; RECODE_OUTER outer = recode_new_outer (true); recode_term_outer (outer); exit (EXIT_SUCCESS); }

but we will not insist on such details in the examples to come.

• Initialisation functions

  RECODE_OUTER recode_new_outer (auto_abort); bool recode_delete_outer (outer);

  The recoding library absolutely needs to be initialised before being used, and recode_new_outer has to be called once, first. Besides the outer it is meant to initialise, the function accepts a Boolean argument whether or not the library should automatically issue diagnostics on standard and abort the whole program on errors. When auto_abort is true, the library later conveniently issues diagnostics itself, and aborts the calling program on errors. This is merely a convenience, because if this parameter was false, the calling program should always take care of checking the return value of all other calls to the recoding library functions, and when any error is detected, issue a diagnostic and abort processing itself.

  Regardless of the setting of auto_abort, all recoding library functions return a success status. Most functions are geared for returning false for an error, and true if everything went fine. Functions returning structures or strings return NULL instead of the result, when the result cannot be produced. If auto_abort is selected, functions either return true, or do not return at all.

  As in the example above, recode_new_outer is called only once in most cases. Calling recode_new_outer implies some overhead, so calling it more than once should preferably be avoided.

  The termination function recode_delete_outer reclaims the memory allocated by recode_new_outer for a given outer variable. Calling recode_delete_outer prior to program termination is more aesthetic then useful, as all memory resources are automatically reclaimed when the program ends. You may spare this terminating call if you prefer.

• The program_name declaration

  As we just explained, the user may set the recode library so that, in case of problems error, it issues the diagnostic itself and aborts the whole processing. This capability may be quite convenient. When this feature is used, the aborting routine includes the name of the running program in the diagnostic. On the other hand, when this feature is not used, the library merely return error codes, giving the library user fuller control over all this. This behaviour is more like what usual libraries do: they return codes and never abort. However, I would rather not force library users to necessarily check all return codes themselves, by leaving no other choice. In most simple applications, letting the library diagnose and abort is much easier, and quite welcome. This is precisely because both possibilities exist that the program_name variable is needed: it may be used by the library when the user sets it to diagnose itself.