MAN page from Mandrake Other XITE-3.3-3.i386.rpm

MESSAGE

Section: C Library Functions (3)
Updated: 16 Mar 1998
Index

NAME

message, Info, Message, Warning, Error, Usage, InitMessage,PushMessage, PopMessage, Verbose, ExitOnError, LastMessage,MessageStream, DefaultMessage, DefaultNoMessage,xite_standard_options_usage_text, xite_app_std_usage_text -print error/warning/info/usage messages

SYNTAX

#include <xite/message.h>

typedef int (*messagefunc)(int, char *);
typedef int (*Messagefunc)(int, char *, ...);

int InitMessage( int* argc, char* argv[],
    char* usage );
int PushMessage( messagefunc info,
    messagefunc warning, messagefunc error,
    int exitonerror );
int PopMessage( void  );

int Info( int id, char* format,  ...);
int Message( int id, char* format,  ...);
int Warning( int id, char* format,  ...);
int Error( int id, char* format,  ...);
int Usage( int id, char* format,  ...);

int Verbose( void  );
int ExitOnError( void  );
char *LastMessage( void  );
FILE *MessageStream( void  );

int DefaultMessage( int id, char* message );
int DefaultNoMessage( int id, char* message );

char *xite_standard_options_usage_text( void );

char *xite_app_std_usage_text( char *usage );

DESCRIPTION

This module defines a set of routines togive information/warning/error/usage messagesin a standard way.

The system is initialized by InitMessage.This routine will save the program name andusage text. All occurrences of %s in the usage textis replaced by the program name (max 5 times).Then it will search the command linefor -help, -usage, -whatis, -man and -verbose switches.If -help/-usage/-whatis/-man ison the command line, the program will exit afterprinting out the usage text/man page. -verbose will setthe verbose flag for the system.At last it will search for the environment variablesVERBOSE and MESSAGEPROG. If the environment variableVERBOSE exists, the verbose flag is set. If theenvironment variable MESSAGEPROG exists the program$MESSAGEPROG is started. All output from the messagesystem is sent to $MESSAGEPROG.

Info,Message,Warning,Error,and Usageare usedto inform the user. The first parameter idis the message number. This may be used as identificationfor installed action routines. A common way to use idis to set id=0 for info, id=1 for warning, and id>=2 forerror. The format on the rest of the parameters behavesexactly like the printf function. Infowill only beexecuted if the verbose flag is set. Messagebehavesexactly like Infoexcept that the message is printed withoutregard to the verboseflag. Usagewill print out aformatted error message followed by the usage text andthen terminate the program with status id.Info,Warningand Errorwill invoke their actionroutines with the parameter idand the formattedtext string. If the flag exitonerroris set, the Errorroutine will terminate the program with status id.When Erroris used from library routines it isimportant to keep in mind that exitonerrormay be FALSE.An advice is to use: return(Error(...)) in library routines.

PushMessagewill install a new set of action routinesand set a new status for the exitonerrorflag.Default action routine is DefaultMessage.This routineprints the message to stderr. Another predefinedaction routine is DefaultNoMessagewhich does nothing.The installed action routine takes two arguments,int idand char *message.If NULL is used as an action routine parameter, theaction remains unchanged. To go back to the previousstate use the function PopMessage.

Verboseand ExitOnErrorwill read the current settingsof the flags verboseand exitonerror.

LastMessagewill return a pointer to the last messagesent to the message system.

MessageStreamreturns a pointer to a streamfor output messages.

xite_app_std_usage_textreturns the concatenation ofusageand the standard usage text forXITE (given by xite_standard_options_usage_text).

xite_standard_options_usage_textreturns a string witha short description of the standard XITE options -help, -usage,-man, -whatis and -verbose.

EXAMPLE

#include <xite/message.h>

int my_error(int id, char *message)
{
   FILE *msg;
   msg = MessageStream();
   fprintf(msg, "**** Error no %d ****\n", id);
   return(id);
}

int lib_func(char *a, char *b)
{
   Info(0, "Library function(%s, %s)\n", a,b);
   if (a==NULL || b == NULL)
     return Error(2,
            "Argument a or b is NULL in lib_func\n");
   / * Do something * /
   return(0); / * Status code 0 = OK * /
}

main(int argc, char *argv[])
{
   int stat;
   InitMessage(&argc, argv,
               "Usage: %s <infile> <outfile>\n");

   Info(0, "Test number of arguments\n");
   if (argc != 3)
     Usage(2,"Wrong number of parameters\n");

Info(0, "Test Warning message\n");
Warning(0, "This is only a test version\n");

   Info(0, "Test PushMessage and PopMessage\n");
   PushMessage(NULL, NULL, my_error, 0);
   stat = Error(3, "This text is not printed\n");
   PopMessage();

lib_func(argv[1], argv[2]);

Info(0, "Test exit on Error\n");
Error(4, "Stat = %d\n", stat);

Warning(0,
"The program will never reach this line\n");
}

RESTRICTIONS

The composed message string must not exceed 2047 bytes.

RETURN VALUE

AUTHOR

Otto Milvang

This document was created byman2html,using the manual pages.