Raising Prolog errors

### 9.5 Raising Prolog errors

- Managing the error context
- Instantiation 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 5.3).

#### 9.5.1 Managing the error context

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

#### 9.5.2 Instantiation error

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

  `void Pl_Err_Instantiation(void)`

#### 9.5.3 Type error

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

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

#### 9.5.4 Domain error

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

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

#### 9.5.5 Existence error

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

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

#### 9.5.6 Permission error

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

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

#### 9.5.7 Representation error

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

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

#### 9.5.8 Evaluation error

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

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

#### 9.5.9 Resource error

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

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

#### 9.5.10 Syntax error

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

  `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 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 `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 7.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")`.

#### 9.5.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 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 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 `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-2009 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright