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):
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):
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.
