ajmess.c

Macro ajFatal

Fatal error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Fatal error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Macro ajMessCrash

Crash error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Crash error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessInvokeDebugger

Used to trace in a debugger as a breakpoint

Synopsis

Prototype

void ajMessInvokeDebugger (
      void
);

Returns

void:No return value

Description

Used to trace in a debugger as a breakpoint

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegBeep

Sets a function to process beeps

Synopsis

Prototype

AjMessVoidRoutine ajMessRegBeep (
      AjMessVoidRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessVoidRoutine:Previously defined function

Description

Sets a function to process beeps

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegOut

Sets a function to write messages

Synopsis

Prototype

AjMessOutRoutine ajMessRegOut (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to write messages

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegDump

Sets a function to dump data

Synopsis

Prototype

AjMessOutRoutine ajMessRegDump (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to dump data

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegErr

Sets a function to report errors

Synopsis

Prototype

AjMessOutRoutine ajMessRegErr (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to report errors

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegExit

Sets a function to exit

Synopsis

Prototype

AjMessOutRoutine ajMessRegExit (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to exit

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegCrash

Sets a function to crash

Synopsis

Prototype

AjMessOutRoutine ajMessRegCrash (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to crash

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessRegWarn

Sets a function to print warnings

Synopsis

Prototype

AjMessOutRoutine ajMessRegWarn (
      AjMessOutRoutine func
);

Input

func:(Function)Function to be registered

Returns

AjMessOutRoutine:Previously defined function

Description

Sets a function to print warnings

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessBeep

Calls the defined beep function, if any. Otherwise prints ASCII 7 to standard error.

Synopsis

Prototype

void ajMessBeep (
      void
);

Returns

void:No return value

Description

Calls the defined beep function, if any. Otherwise prints ASCII 7 to standard error.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajUser

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

Synopsis

Prototype

void ajUser (
      const char* format,
      ...
);

Input

format:(Input)Format string
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessOut

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with no newline.

Synopsis

Prototype

void ajMessOut (
      const char* format,
      ...
);

Input

format:(Input)Format string
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with no newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajVUser

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error.

Synopsis

Prototype

void ajVUser (
      const char* format,
      va_list args
);

Input

format:(Input)Format string
args:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessDump

Formats a message. Calls the dump function (if any). Otherwise no further action.

Synopsis

Prototype

void ajMessDump (
      const char* format,
      ...
);

Input

format:(Input)format string.
:(Vararg)Variable length argument list.

Returns

void:No return value

Description

Formats a message. Calls the dump function (if any). Otherwise no further action.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessErrorCount

Returns the number of times the error routines have been called.

Synopsis

Prototype

ajint ajMessErrorCount (
      void
);

Returns

ajint:Error function call count.

Description

Returns the number of times the error routines have been called.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajErr

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Synopsis

Prototype

void ajErr (
      const char* format,
      ...
);

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajVErr

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Synopsis

Prototype

void ajVErr (
      const char* format,
      va_list args
);

Input

format:(Input)Format
args:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajDie

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Synopsis

Prototype

void ajDie (
      const char* format,
      ...
);

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajVDie

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Synopsis

Prototype

void ajVDie (
      const char* format,
      va_list args
);

Input

format:(Input)Format
args:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajWarn

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Synopsis

Prototype

void ajWarn (
      const char* format,
      ...
);

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajVWarn

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Synopsis

Prototype

void ajVWarn (
      const char* format,
      va_list args
);

Input

format:(Input)Format
args:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessExitmsg

Formats an exit message and calls the exit function (if any). Otherwise prints the message to standard error with a trailing newline and exist with code EXIT_FAILURE.

Use this function for errors that while being unrecoverable are not a problem with the AJAX code.

Note that there errors are logged but that this routine will exit without any chance to interrupt it (see the crash routine in ajMessCrashFL), this could be changed to allow the application to register an exit handler.

Synopsis

Prototype

void ajMessExitmsg (
      const char* format,
      ...
);

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

Formats an exit message and calls the exit function (if any). Otherwise prints the message to standard error with a trailing newline and exist with code EXIT_FAILURE.

Use this function for errors that while being unrecoverable are not a problem with the AJAX code.

Note that there errors are logged but that this routine will exit without any chance to interrupt it (see the crash routine in ajMessCrashFL), this could be changed to allow the application to register an exit handler.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessCrashFL

This is the routine called by the ajFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Synopsis

Prototype

void ajMessCrashFL (
      const char* format,
      ...
);

Input

format:(Input)Format
:(Vararg)Variable length argument list

Returns

void:No return value

Description

This is the routine called by the ajFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessVCrashFL

This is the routine called by the ajVFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Synopsis

Prototype

void ajMessVCrashFL (
      const char* format,
      va_list args
);

Input

format:(Input)Format
args:(Vararg)Variable length argument list

Returns

void:No return value

Description

This is the routine called by the ajVFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessCaughtMessage

Returns the current message text.

Synopsis

Prototype

char* ajMessCaughtMessage (
      void
);

Returns

char*:Message text

Description

Returns the current message text.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessSysErrorText

Returns the system message text from 'strerror' from the standard C library.

Synopsis

Prototype

char* ajMessSysErrorText (
      void
);

Returns

char*:System error message.

Description

Returns the system message text from 'strerror' from the standard C library.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessErrorInit

Initialises the stored program name.

Synopsis

Prototype

void ajMessErrorInit (
      const char* progname
);

Input

progname:(Input)Program name.

Returns

void:No return value

Description

Initialises the stored program name.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessSetErr

Stores the source file name (converted to a base name) and the source line number to be reported by the crash routines.

Invoked automatically by a macro (e.g. ajFatal) where needed.

Synopsis

Prototype

void ajMessSetErr (
      const char* filename,
      ajint line_num
);

Input

filename:(Input)source filename, __FILE__
line_num:(Input)source line number, __LINE__

Returns

void:No return value

Description

Stores the source file name (converted to a base name) and the source line number to be reported by the crash routines.

Invoked automatically by a macro (e.g. ajFatal) where needed.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessErrorSetFile

Opens a file and sets this to be the error file.

Synopsis

Prototype

AjBool ajMessErrorSetFile (
      const char* errfile
);

Input

errfile:(Input)Error file name

Returns

AjBool:ajTrue on success

Description

Opens a file and sets this to be the error file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessOutCode

Writes an output message for a given message code.

Synopsis

Prototype

void ajMessOutCode (
      const char* code
);

Input

code:(Input)Message code

Returns

void:No return value

Description

Writes an output message for a given message code.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessErrorCode

Writes an error message for a given message code.

Synopsis

Prototype

void ajMessErrorCode (
      const char* code
);

Input

code:(Input)Error code

Returns

void:No return value

Description

Writes an error message for a given message code.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessCrashCodeFL

Writes an error message for a given message code and crashes.

Synopsis

Prototype

void ajMessCrashCodeFL (
      const char* code
);

Input

code:(Input)Error code

Returns

void:No return value

Description

Writes an error message for a given message code and crashes.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessCodesDelete

Deletes the message codes table.

Synopsis

Prototype

void ajMessCodesDelete (
      void
);

Returns

void:No return value

Description

Deletes the message codes table.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajDebug

Writes a debug message to the debug file if debugging is on. Typically, debugging is turned on by adding '-debug' to the command line or by defining a variable prefix_DEBUG

Avoid using this call in any code which can be invoked before the command line processing is complete as it can be a problem to find a reasonable file name for debug output under these circumstances.

Synopsis

Prototype

void ajDebug (
      const char* fmt,
      ...
);

Input

fmt:(Input)Format.
:(Vararg)Variable argument list.

Returns

void:No return value

Description

Writes a debug message to the debug file if debugging is on. Typically, debugging is turned on by adding '-debug' to the command line or by defining a variable prefix_DEBUG

Avoid using this call in any code which can be invoked before the command line processing is complete as it can be a problem to find a reasonable file name for debug output under these circumstances.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajDebugFile

Returns the file used for debug output, or NULL if no debug file is open.

Synopsis

Prototype

FILE* ajDebugFile (
      void
);

Returns

FILE*:C runtime library file handle for debug output.

Description

Returns the file used for debug output, or NULL if no debug file is open.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajUserGet

Writes a prompt to the terminal and reads one line from the user.

Synopsis

Prototype

ajint ajUserGet (
      AjPStr* pthis,
      const char* fmt,
      ...
);

Input

fmt:(Input)Format string
:(Vararg)Variable argument list.

Output

pthis:(Output)Buffer for the user response.

Returns

ajint:Length of response string.

Description

Writes a prompt to the terminal and reads one line from the user.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0

Function ajMessExit

Delete any static initialised values

Synopsis

Prototype

void ajMessExit (
      void
);

Returns

void:No return value

Description

Delete any static initialised values

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

See Also

See other functions in this section

Availability

In release 3.0.0