Previous Contents Next
8.3 Raising Prolog errors
The following functions allows a C function to raise a Prolog error. Refer to the section concerning Prolog errors for more information about the effect of raising an error (section 4.3).

8.3.1 Managing the error context
When one of the following error function is invoked it refers to the implicit error context (section 4.3.1). This context indicates the name and the arity of the concerned predicate. When using a foreign/2 declaration this context is set by default to the name and arity of the associated Prolog predicate. This can be controlled using the bip_name option (section 8.1.2). In any case, the following functions can also be used to modify this context:

void Set_C_Bip_Name  (char *functor, int arity)
void Unset_C_Bip_Name(void)
The function Set_C_Bip_Name(functor, arity) initializes the context of the error with functor and arity (if arity<0 only functor is significant). The function Unset_C_Bip_Name() removes such an initialization (the context is then reset to the last Functor/Arity set by a call to set_bip_name/2 (section 6.22.3). This is useful when writing a C routine to define a context for errors occurring in this routine and, before exiting to restore the previous context.

8.3.2 Instantiation error
The following function raises an instantiation error (section 4.3.2):

void Pl_Err_Instantiation(void)
8.3.3 Type error
The following function raises a type error (section 4.3.3):

void Pl_Err_Type(int atom_type, PlTerm culprit)
atom_type is (the internal key of) the atom associated to the expected type. For each type name T there is a corresponding predefined atom stored in a global variable whose name is of the form type_T. culprit is the argument which caused the error.

Example: x is an atom while an integer was expected: Pl_Err_Type(type_integer, x).

8.3.4 Domain error
The following function raises a domain error (section 4.3.4):

void Pl_Err_Domain(int atom_domain, PlTerm culprit)
atom_domain is (the internal key of) the atom associated to the expected domain. For each domain name D there is a corresponding predefined atom stored in a global variable whose name is of the form domain_D. culprit is the argument which caused the error.

Example: x is < 0 but should be ³ 0: Pl_Err_Domain(domain_not_less_than_zero, x).

8.3.5 Existence error
The following function raises an existence error (section 4.3.5):

void Pl_Err_Existence(int atom_object, PlTerm culprit)
atom_object is (the internal key of) the atom associated to the type of the object. For each object name O there is a corresponding predefined atom stored in a global variable whose name is of the form existence_O. culprit is the argument which caused the error.

Example: x does not refer to an existing source: Pl_Err_Existence(existence_source_sink, x).

8.3.6 Permission error
The following function raises a permission error (section 4.3.6):

void Pl_Err_Permission(int atom_operation, int atom_permission, PlTerm culprit)
atom_operation is (the internal key of) the atom associated to the operation which caused the error. For each operation name O there is a corresponding predefined atom stored in a global variable whose name is of the form permission_operation_O. atom_permission is (the internal key of) the atom associated to the tried permission. For each permission name P there is a corresponding predefined atom stored in a global variable whose name is of the form permission_type_P. culprit is the argument which caused the error.

Example: reading from an output stream x: Pl_Err_Permission(permission_operation_input,
permission_type_stream, x)
.

8.3.7 Representation error
The following function raises a representation error (section 4.3.7):

void Pl_Err_Representation(int atom_limit)
atom_limit is (the internal key of) the atom associated to the reached limit. For each limit name L there is a corresponding predefined atom stored in a global variable whose name is of the form representation_L.

Example: an arity too big occurs: Pl_Err_Representation(representation_max_arity).

8.3.8 Evaluation error
The following function raises an evaluation error (section 4.3.8):

void Pl_Err_Evaluation(int atom_error)
atom_error is (the internal key of) the atom associated to the error. For each evaluation error name E there is a corresponding predefined atom stored in a global variable whose name is of the form evaluation_E.

Example: a division by zero occurs: Pl_Err_Evaluation(evluation_zero_divisor).

8.3.9 Resource error
The following function raises a resource error (section 4.3.9):

void Pl_Err_Resource(int atom_resource)
atom_resource is (the internal key of) the atom associated to the resource. For each resource error name R there is a corresponding predefined atom stored in a global variable whose name is of the form resource_R.

Example: too many open streams: Pl_Err_Resource(resource_too_many_open_streams).

8.3.10 Syntax error
The following function raises a syntax error (section 4.3.10):

void Pl_Err_Syntax(int atom_error)
atom_error is (the internal key of) the atom associated to the error. There is no predefined syntax error atoms.

Example: a / is expected: Pl_Err_Syntax(Create_Atom("/ expected")).

The following function emits a syntax error according to the value of the syntax_error Prolog flag (section 6.22.1). This function can then return (if the value of the flag is either warning or fail). In that case the calling function should fail (e.g. returning FALSE). This function accepts a file name (the empty string C "" can be passed), a line and column number and an error message string. Using this function makes it possible to further call the built-in predicate syntax_error_info/4 (section 6.14.4):

void Emit_Syntax_Error(char *file_name, int line, int column, char *message)
Example: a / is expected: Emit_Syntax_Error("data", 10, 30, "/ expected").

8.3.11 System error
The following function raises a system error (4.3.11, page *):

void Pl_Err_System(int atom_error)
atom_error is (the internal key of) the atom associated to the error. There is no predefined system error atoms.

Example: an invalid pathname is given: Pl_Err_System(Create_Atom("invalid path name")).

The following function emits a system error associated to an operating system error according to the value of the os_error Prolog flag (section 6.22.1). This function can then return (if the value of the flag is either warning or fail). In that case the calling function should fail (e.g. returning FALSE). This function uses the value of the errno C library variable:

void Os_Error(void)
Example: a call to the C Unix function chdir(3) returns -1: Os_Error().


Copyright (C) 1999,2000 Daniel Diaz

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

More about the copyright
Previous Contents Next