<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
Raising Prolog errors
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="manual067.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual065.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual069.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66dbff"><DIV ALIGN=center><TABLE>
<TR><TD><FONT SIZE=4><B><A NAME="htoc362">9.3</A></B></FONT></TD>
<TD WIDTH="100%" ALIGN=center><FONT SIZE=4><B>Raising Prolog errors</B></FONT></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><UL>
<LI><A HREF="manual068.html#toc296"> Managing the error context</A>
<LI><A HREF="manual068.html#toc297"> Instantiation error</A>
<LI><A HREF="manual068.html#toc298"> Type error</A>
<LI><A HREF="manual068.html#toc299"> Domain error</A>
<LI><A HREF="manual068.html#toc300"> Existence error</A>
<LI><A HREF="manual068.html#toc301"> Permission error</A>
<LI><A HREF="manual068.html#toc302"> Representation error</A>
<LI><A HREF="manual068.html#toc303"> Evaluation error</A>
<LI><A HREF="manual068.html#toc304"> Resource error</A>
<LI><A HREF="manual068.html#toc305"> Syntax error</A>
<LI><A HREF="manual068.html#toc306"> System error</A>
</UL>
<A NAME="Raising-Prolog-errors"></A>
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 <A HREF="manual019.html#Errors">5.3</A>).<BR>
<BR>
<A NAME="toc296"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc363">9.3.1</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Managing the error context</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
When one of the following error function is invoked it refers to the
implicit error context (section <A HREF="manual019.html#General-format-and-error-context">5.3.1</A>). This
context indicates the name and the arity of the concerned predicate. When
using a <TT>foreign/2</TT> declaration this context is set by default to the
name and arity of the associated Prolog predicate. This can be controlled
using the <TT>bip_name</TT> option (section <A HREF="manual066.html#foreign/2-directive">9.1.2</A>). In any
case, the following functions can also be used to modify this context:
<DL COMPACT=compact><DT><DD>
<PRE>
void Set_C_Bip_Name (char *functor, int arity)
void Unset_C_Bip_Name(void)
</PRE></DL>
The function <TT>Set_C_Bip_Name(functor, arity)</TT> initializes the
context of the error with <TT>functor</TT> and <TT>arity</TT> (if
<TT>arity</TT><0 only <TT>functor</TT> is significant). The function
<TT>Unset_C_Bip_Name()</TT> removes such an initialization (the context
is then reset to the last <TT>Functor</TT>/<TT>Arity</TT> set by a call to
<TT>set_bip_name/2</TT> (section <A HREF="manual045.html#set-bip-name/2">7.22.3</A>). 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.<BR>
<BR>
<A NAME="toc297"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc364">9.3.2</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Instantiation error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises an instantiation error (section <A HREF="manual019.html#Instantiation-error">5.3.2</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Instantiation(void)</TT></DL>
<A NAME="toc298"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc365">9.3.3</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Type error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a type error (section <A HREF="manual019.html#Type-error">5.3.3</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Type(int atom_type, PlTerm culprit)</TT></DL>
<TT>atom_type</TT> is (the internal key of) the atom associated to the
expected type. For each type name <I><TT>T</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>type_<I>T</I></TT>. <TT>culprit</TT> is the argument which
caused the error.<BR>
<BR>
<B>Example</B>: <TT>x</TT> is an atom while an integer was expected:
<TT>Pl_Err_Type(type_integer, x)</TT>.<BR>
<BR>
<A NAME="toc299"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc366">9.3.4</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Domain error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a domain error (section <A HREF="manual019.html#Domain-error">5.3.4</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Domain(int atom_domain, PlTerm culprit)</TT></DL>
<TT>atom_domain</TT> is (the internal key of) the atom associated to the
expected domain. For each domain name <I><TT>D</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>domain_<I>D</I></TT>. <TT>culprit</TT> is the argument which
caused the error.<BR>
<BR>
<B>Example</B>: <TT>x</TT> is < 0 but should be >= 0:
<TT>Pl_Err_Domain(domain_not_less_than_zero, x)</TT>.<BR>
<BR>
<A NAME="toc300"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc367">9.3.5</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Existence error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises an existence error (section <A HREF="manual019.html#Existence-error">5.3.5</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Existence(int atom_object, PlTerm culprit)</TT></DL>
<TT>atom_object</TT> is (the internal key of) the atom associated to the
type of the object. For each object name <I><TT>O</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>existence_<I>O</I></TT>. <TT>culprit</TT> is the argument
which caused the error.<BR>
<BR>
<B>Example</B>: <TT>x</TT> does not refer to an existing source:
<TT>Pl_Err_Existence(existence_source_sink, x)</TT>.<BR>
<BR>
<A NAME="toc301"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc368">9.3.6</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Permission error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a permission error (section <A HREF="manual019.html#Permission-error">5.3.6</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Permission(int atom_operation, int atom_permission,
PlTerm culprit)</TT></DL>
<TT>atom_operation</TT> is (the internal key of) the atom associated to the
operation which caused the error. For each operation name
<I><TT>O</TT></I> there is a corresponding predefined atom stored in a
global variable whose name is of the form
<TT>permission_operation_<I>O</I></TT>. <TT>atom_permission</TT> is
(the internal key of) the atom associated to the tried permission. For each
permission name <I><TT>P</TT></I> there is a corresponding predefined atom
stored in a global variable whose name is of the form
<TT>permission_type_<I>P</I></TT>. <TT>culprit</TT> is the argument
which caused the error.<BR>
<BR>
<B>Example</B>: reading from an output stream <TT>x</TT>:
<TT>Pl_Err_Permission(permission_operation_input,<BR>
permission_type_stream, x)</TT>.<BR>
<BR>
<A NAME="toc302"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc369">9.3.7</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Representation error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a representation error (section <A HREF="manual019.html#Representation-error">5.3.7</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Representation(int atom_limit)</TT></DL>
<TT>atom_limit</TT> is (the internal key of) the atom associated to the
reached limit. For each limit name <I><TT>L</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>representation_<I>L</I></TT>.<BR>
<BR>
<B>Example</B>: an arity too big occurs:
<TT>Pl_Err_Representation(representation_max_arity)</TT>.<BR>
<BR>
<A NAME="toc303"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc370">9.3.8</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Evaluation error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises an evaluation error (section <A HREF="manual019.html#Evaluation-error">5.3.8</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Evaluation(int atom_error)</TT></DL>
<TT>atom_error</TT> is (the internal key of) the atom associated to the
error. For each evaluation error name <I><TT>E</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>evaluation_<I>E</I></TT>.<BR>
<BR>
<B>Example</B>: a division by zero occurs:
<TT>Pl_Err_Evaluation(evluation_zero_divisor)</TT>.<BR>
<BR>
<A NAME="toc304"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc371">9.3.9</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Resource error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a resource error (section <A HREF="manual019.html#Resource-error">5.3.9</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Resource(int atom_resource)</TT></DL>
<TT>atom_resource</TT> is (the internal key of) the atom associated to the
resource. For each resource error name <I><TT>R</TT></I> there is a
corresponding predefined atom stored in a global variable whose name is of
the form <TT>resource_<I>R</I></TT>.<BR>
<BR>
<B>Example</B>: too many open streams:
<TT>Pl_Err_Resource(resource_too_many_open_streams)</TT>.<BR>
<BR>
<A NAME="toc305"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc372">9.3.10</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Syntax error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a syntax error (section <A HREF="manual019.html#Syntax-error">5.3.10</A>):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_Syntax(int atom_error)</TT></DL>
<TT>atom_error</TT> is (the internal key of) the atom associated to the
error. There is no predefined syntax error atoms. <BR>
<BR>
<B>Example</B>: a <TT>/</TT> is expected:
<TT>Pl_Err_Syntax(Create_Atom("/ expected"))</TT>.<BR>
<BR>
The following function emits a syntax error according to the value of the
<TT>syntax_error</TT> Prolog flag (section <A HREF="manual045.html#set-prolog-flag/2">7.22.1</A>). This
function can then return (if the value of the flag is either
<TT>warning</TT> or <TT>fail</TT>). In that case the calling function should
fail (e.g. returning <TT>FALSE</TT>). This function accepts a file name (the
empty string C <TT>""</TT> 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 <TT>syntax_error_info/4</TT>
(section <A HREF="manual037.html#syntax-error-info/4">7.14.4</A>):
<DL COMPACT=compact><DT><DD><TT>void Emit_Syntax_Error(char *file_name, int line, int column,
char *message)</TT></DL>
<B>Example</B>: a <TT>/</TT> is expected:
<TT>Emit_Syntax_Error("data", 10, 30, "/ expected")</TT>.<BR>
<BR>
<A NAME="toc306"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc373">9.3.11</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>System error</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The following function raises a system error (4.3.11, page *):
<DL COMPACT=compact><DT><DD><TT>void Pl_Err_System(int atom_error)</TT></DL>
<TT>atom_error</TT> is (the internal key of) the atom associated to the
error. There is no predefined system error atoms. <BR>
<BR>
<B>Example</B>: an invalid pathname is given:
<TT>Pl_Err_System(Create_Atom("invalid path name"))</TT>.<BR>
<BR>
The following function emits a system error associated to an operating
system error according to the value of the <TT>os_error</TT>
Prolog flag (section <A HREF="manual045.html#set-prolog-flag/2">7.22.1</A>). This function can then return (if the value of the flag is either <TT>warning</TT> or <TT>fail</TT>).
In that case the calling function should fail (e.g. returning
<TT>FALSE</TT>). This function uses the value of the <TT>errno</TT> C
library variable:
<DL COMPACT=compact><DT><DD><TT>void Os_Error(void)</TT></DL>
<B>Example</B>: a call to the C Unix function <TT>chdir(3)</TT> returns
<TT>-1</TT>: <TT>Os_Error()</TT>.<BR>
<BR>
<HR SIZE=2>
Copyright (C) 1999-2002 Daniel Diaz
<BR>
<BR>
Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved. <BR>
<BR>
<A HREF="index.html#copyright">More about the copyright</A>
<HR>
<A HREF="manual067.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual065.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual069.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
