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 5.3).
When one of the following error function is invoked it refers to the implicit error context (section 5.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 9.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 7.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.
The following function raises an instantiation error (section 5.3.2):
The following function raises a type error (section 5.3.3):
atom_type is (the internal key of) the atom associated with 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).
The following function raises a domain error (section 5.3.4):
atom_domain is (the internal key of) the atom associated with 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).
The following function raises an existence error (section 5.3.5):
atom_object is (the internal key of) the atom associated with 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).
The following function raises a permission error (section 5.3.6):
atom_operation is (the internal key of) the atom associated with 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 with 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).
The following function raises a representation error (section 5.3.7):
atom_limit is (the internal key of) the atom associated with 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).
The following function raises an evaluation error (section 5.3.8):
atom_error is (the internal key of) the atom associated with 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).
The following function raises a resource error (section 5.3.9):
atom_resource is (the internal key of) the atom associated with 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).
The following function raises a syntax error (section 5.3.10):
atom_error is (the internal key of) the atom associated with 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 7.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 7.14.4):
Example: a / is expected: Emit_Syntax_Error("data", 10, 30, "/ expected").
The following function raises a system error (4.3.11, page *):
atom_error is (the internal key of) the atom associated with 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 with an operating system error according to the value of the os_error Prolog flag (section 7.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:
Example: a call to the C Unix function chdir(3) returns -1: Os_Error().