Raising Prolog errors
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 10.5 Raising Prolog errors

- Managing the error context
- Instantiation error
- Uninstantiation error
- Type error
- Domain error
- Existence error
- Permission error
- Representation error
- Evaluation error
- Resource error
- Syntax error
- System error

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

#### 10.5.1 Managing the error context

When one of the following error function is invoked it refers to the implicit error context (section 6.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 10.3.2). In any case, the following functions can also be used to modify this context:

      void Pl_Set_C_Bip_Name  (const char *functor, int arity)
      void Pl_Unset_C_Bip_Name(void)

The function Pl_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 Pl_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 8.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.

#### 10.5.2 Instantiation error

The following function raises an instantiation error (section 6.3.2):

  void Pl_Err_Instantiation(void)

#### 10.5.3 Uninstantiation error

The following function raises an uninstantiation error (section 6.3.3):

  void Pl_Err_Uninstantiation( PlTerm culprit)

#### 10.5.4 Type error

The following function raises a type error (section 6.3.4):

  void Pl_Err_Type(int atom_type, PlTerm culprit)

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 pl_type_T. culprit is the argument which caused the error.

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

#### 10.5.5 Domain error

The following function raises a domain error (section 6.3.5):

  void Pl_Err_Domain(int atom_domain, PlTerm culprit)

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(pl_domain_not_less_than_zero, x).

#### 10.5.6 Existence error

The following function raises an existence error (section 6.3.6):

  void Pl_Err_Existence(int atom_object, PlTerm culprit)

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 pl_existence_O. culprit is the argument which caused the error.

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

#### 10.5.7 Permission error

The following function raises a permission error (section 6.3.7):

  void Pl_Err_Permission(int atom_operation, int atom_permission, PlTerm culprit)

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 pl_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 pl_permission_type_P. culprit is the argument which caused the error.

Example: reading from an output stream x: Pl_Err_Permission(pl_permission_operation_input,
pl_permission_type_stream, x).

#### 10.5.8 Representation error

The following function raises a representation error (section 6.3.8):

  void Pl_Err_Representation(int atom_limit)

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 pl_representation_L.

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

#### 10.5.9 Evaluation error

The following function raises an evaluation error (section 6.3.9):

  void Pl_Err_Evaluation(int atom_error)

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 pl_evaluation_E.

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

#### 10.5.10 Resource error

The following function raises a resource error (section 6.3.10):

  void Pl_Err_Resource(int atom_resource)

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 pl_resource_R.

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

#### 10.5.11 Syntax error

The following function raises a syntax error (section 6.3.11):

  void Pl_Err_Syntax(int atom_error)

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(Pl_Create_Atom("/ expected")).

The following function emits a syntax error according to the value of the syntax_error Prolog flag (section 8.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 PL_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 8.14.4):

  void Pl_Emit_Syntax_Error(char *file_name, int line, int column, char *message)

Example: a / is expected: Pl_Emit_Syntax_Error("data", 10, 30, "/ expected").

#### 10.5.12 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 with the error. There is no predefined system error atoms.

Example: an invalid pathname is given: Pl_Err_System(Pl_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 8.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 PL_FALSE).

The following function uses the value of the errno C library variable (basically it calls Pl_Err_System with the result of strerror(errno)).

  void Pl_Os_Error(void)

Example: if a call to the C Unix function chdir(2) returns -1 then call Os_Error().

Copyright (C) 1999-2021 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright