<HTML> <HEAD> <!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 --> <LINK rel="stylesheet" href="ciao.css" type="text/css"> <TITLE>The Ciao Prolog System - Foreign Language Interface Properties</TITLE> </HEAD> <BODY> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_120.html">previous</A>, <A HREF="ciao_122.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC523" HREF="ciao_toc.html#TOC523">Foreign Language Interface Properties</A></H1> <P> <A NAME="IDX5791"></A> <P> <STRONG>Author(s):</STRONG> Jose Morales, Manuel Carro. <P> <STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST) <P> <STRONG>Version of last change:</STRONG> 1.9#229 (2003/12/22, 17:34:59 CET) <P> The foreign language interface uses some properties to specify linking regimes, foreign files to be compiled, types of data available, memory allocation policies, etc. <UL> <LI><A HREF="ciao_121.html#SEC524">Usage and interface (foreign_interface_properties)</A> <LI><A HREF="ciao_121.html#SEC525">Documentation on exports (foreign_interface_properties)</A> <LI><A HREF="ciao_121.html#SEC526">Documentation on internals (foreign_interface_properties)</A> <LI><A HREF="ciao_121.html#SEC527">Known bugs and planned improvements (foreign_interface_properties)</A> </UL> <H2><A NAME="SEC524" HREF="ciao_toc.html#TOC524">Usage and interface (<CODE>foreign_interface_properties</CODE>)</A></H2> <div class="cartouche"> <UL> <LI><STRONG>Library usage:</STRONG> <CODE>:- use_module(library(foreign_interface_properties)).</CODE> <LI><STRONG>Exports:</STRONG> <UL> <LI><EM>Properties:</EM> <A NAME="IDX5792"></A> <CODE>native/1</CODE>, <A NAME="IDX5793"></A> <CODE>native/2</CODE>, <A NAME="IDX5794"></A> <CODE>size_of/3</CODE>, <A NAME="IDX5795"></A> <CODE>foreign/1</CODE>, <A NAME="IDX5796"></A> <CODE>foreign/2</CODE>, <A NAME="IDX5797"></A> <CODE>returns/2</CODE>, <A NAME="IDX5798"></A> <CODE>do_not_free/2</CODE>. <LI><EM>Regular Types:</EM> <A NAME="IDX5799"></A> <CODE>int_list/1</CODE>, <A NAME="IDX5800"></A> <CODE>byte_list/1</CODE>, <A NAME="IDX5801"></A> <CODE>byte/1</CODE>, <A NAME="IDX5802"></A> <CODE>null/1</CODE>, <A NAME="IDX5803"></A> <CODE>address/1</CODE>, <A NAME="IDX5804"></A> <CODE>any_term/1</CODE>. </UL> </UL> </div class="cartouche"> <H2><A NAME="SEC525" HREF="ciao_toc.html#TOC525">Documentation on exports (<CODE>foreign_interface_properties</CODE>)</A></H2> <P> <A NAME="IDX5805"></A> <A NAME="IDX5806"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>int_list/1:</B> <DD><A NAME="IDX5807"></A> <P> <STRONG>Usage:</STRONG> <CODE>int_list(List)</CODE> <UL> <LI><EM>Description:</EM> <CODE>List</CODE> is a list of integers. </UL> </DL> <P> <A NAME="IDX5808"></A> <A NAME="IDX5809"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>byte_list/1:</B> <DD><A NAME="IDX5810"></A> <P> <STRONG>Usage:</STRONG> <CODE>byte_list(List)</CODE> <UL> <LI><EM>Description:</EM> <CODE>List</CODE> is a list of bytes. </UL> </DL> <P> <A NAME="IDX5811"></A> <A NAME="IDX5812"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>byte/1:</B> <DD><A NAME="IDX5813"></A> <P> <STRONG>Usage:</STRONG> <CODE>byte(Byte)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Byte</CODE> is a byte. </UL> </DL> <P> <A NAME="IDX5814"></A> <A NAME="IDX5815"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>null/1:</B> <DD><A NAME="IDX5816"></A> <P> <STRONG>Usage:</STRONG> <CODE>null(Address)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Address</CODE> is a null adress. </UL> </DL> <P> <A NAME="IDX5817"></A> <A NAME="IDX5818"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>address/1:</B> <DD><A NAME="IDX5819"></A> <P> <STRONG>Usage:</STRONG> <CODE>address(Address)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Address</CODE> is a memory address. </UL> </DL> <P> <A NAME="IDX5820"></A> <A NAME="IDX5821"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>any_term/1:</B> <DD><A NAME="IDX5822"></A> <P> <STRONG>Usage:</STRONG> <CODE>any_term(X)</CODE> <UL> <LI><EM>Description:</EM> <CODE>X</CODE> is any term. The foreign interface passes it to C functions as a general term. </UL> </DL> <P> <A NAME="IDX5823"></A> <A NAME="IDX5824"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>native/1:</B> <DD><A NAME="IDX5825"></A> <P> <STRONG>Usage:</STRONG> <CODE>native(Name)</CODE> <UL> <LI><EM>Description:</EM> The Prolog predicate <A NAME="IDX5826"></A> <CODE>Name</CODE> is implemented using the function <CODE>Name</CODE>. The implementation is not a common C one, but it accesses directly the internal Ciao Prolog data structures and functions, and therefore no glue code is generated for it. </UL> </DL> <P> <A NAME="IDX5827"></A> <A NAME="IDX5828"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>native/2:</B> <DD><A NAME="IDX5829"></A> <P> <STRONG>Usage:</STRONG> <CODE>native(PrologName, ForeignName)</CODE> <UL> <LI><EM>Description:</EM> The Prolog predicate <A NAME="IDX5830"></A> <CODE>PrologName</CODE> is implemented using the function <CODE>ForeignName</CODE>. The same considerations as above example are to be applied. </UL> </DL> <P> <A NAME="IDX5831"></A> <A NAME="IDX5832"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>size_of/3:</B> <DD><A NAME="IDX5833"></A> <P> <STRONG>Usage:</STRONG> <CODE>size_of(Name, ListVar, SizeVar)</CODE> <UL> <LI><EM>Description:</EM> For predicate <CODE>Name</CODE>, the size of the argument of type <A NAME="IDX5834"></A> <CODE>byte_list/1</CODE>, <CODE>ListVar</CODE>, is given by the argument of type integer <CODE>SizeVar</CODE>. </UL> </DL> <P> <A NAME="IDX5835"></A> <A NAME="IDX5836"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>foreign/1:</B> <DD><A NAME="IDX5837"></A> <P> <STRONG>Usage:</STRONG> <CODE>foreign(Name)</CODE> <UL> <LI><EM>Description:</EM> The Prolog predicate <A NAME="IDX5838"></A> <CODE>Name</CODE> is implemented using the foreign function <CODE>Name</CODE>. </UL> </DL> <P> <A NAME="IDX5839"></A> <A NAME="IDX5840"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>foreign/2:</B> <DD><A NAME="IDX5841"></A> <P> <STRONG>Usage:</STRONG> <CODE>foreign(PrologName, ForeignName)</CODE> <UL> <LI><EM>Description:</EM> The Prolog predicate <A NAME="IDX5842"></A> <CODE>PrologName</CODE> is implemented using the foreign function <CODE>ForeignName</CODE>. </UL> </DL> <P> <A NAME="IDX5843"></A> <A NAME="IDX5844"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>returns/2:</B> <DD><A NAME="IDX5845"></A> <P> <STRONG>Usage:</STRONG> <CODE>returns(Name, Var)</CODE> <UL> <LI><EM>Description:</EM> The result of the foreign function that implements the Prolog predicate <A NAME="IDX5846"></A> <CODE>Name</CODE> is unified with the Prolog variable <CODE>Var</CODE>. Cannot be used without <A NAME="IDX5847"></A> <CODE>foreign/1</CODE> or <A NAME="IDX5848"></A> <CODE>foreign/2</CODE>. </UL> </DL> <P> <A NAME="IDX5849"></A> <A NAME="IDX5850"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>do_not_free/2:</B> <DD><A NAME="IDX5851"></A> <P> <STRONG>Usage:</STRONG> <CODE>do_not_free(Name, Var)</CODE> <UL> <LI><EM>Description:</EM> For predicate <CODE>Name</CODE>, the C argument passed to (returned from) the foreign function will not be freed after calling the foreign function. </UL> </DL> <H2><A NAME="SEC526" HREF="ciao_toc.html#TOC526">Documentation on internals (<CODE>foreign_interface_properties</CODE>)</A></H2> <P> <A NAME="IDX5852"></A> <A NAME="IDX5853"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_foreign_source/1:</B> <DD><A NAME="IDX5854"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_foreign_source(Files)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Files</CODE> is the (list of) foreign file(s) that will be linked with the glue-code file. <LI><EM>The following properties hold at call time:</EM> <CODE>Files</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5855"></A> <A NAME="IDX5856"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_foreign_source/2:</B> <DD><A NAME="IDX5857"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_foreign_source(OsArch, Files)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Files</CODE> are the OS and architecture dependant foreign files. This allows compiling and linking different files depending on the O.S. and architecture. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Files</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5858"></A> <A NAME="IDX5859"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_foreign_library/1:</B> <DD><A NAME="IDX5860"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_foreign_library(Libs)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Libs</CODE> is the (list of) external library(es) needed to link the C files. Only the short name of the library (i.e., what would follow the <CODE>-l</CODE> in the linker is needed. <LI><EM>The following properties hold at call time:</EM> <CODE>Libs</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5861"></A> <A NAME="IDX5862"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_foreign_library/2:</B> <DD><A NAME="IDX5863"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_foreign_library(OsArch, Libs)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Libs</CODE> are the OS and architecture dependant libraries. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Libs</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5864"></A> <A NAME="IDX5865"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>extra_compiler_opts/1:</B> <DD><A NAME="IDX5866"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>extra_compiler_opts(Opts)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Opts</CODE> is the list of additional compiler options (e.g., optimization options) that will be used during the compilation. <LI><EM>The following properties hold at call time:</EM> <CODE>Opts</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5867"></A> <A NAME="IDX5868"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>extra_compiler_opts/2:</B> <DD><A NAME="IDX5869"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>extra_compiler_opts(OsArch, Opts)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Opts</CODE> are the OS and architecture dependant additional compiler options. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Opts</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5870"></A> <A NAME="IDX5871"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_compiler/1:</B> <DD><A NAME="IDX5872"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_compiler(Compiler)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Compiler</CODE> is the compiler to use in this file. When this option is used, the default (Ciao-provided) compiler options are not used; those specified in <A NAME="IDX5873"></A> <CODE>extra_compiler_options</CODE> are used instead. <LI><EM>The following properties hold at call time:</EM> <CODE>Compiler</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <P> <A NAME="IDX5874"></A> <A NAME="IDX5875"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_compiler/2:</B> <DD><A NAME="IDX5876"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_compiler(OsArch, Compiler)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Compiler</CODE> is the compiler to use in this file when compiling for the architecture <CODE>OsArch</CODE>. The option management is the same as in <A NAME="IDX5877"></A> <CODE>use_compiler/2</CODE>. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Compiler</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <P> <A NAME="IDX5878"></A> <A NAME="IDX5879"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>extra_linker_opts/1:</B> <DD><A NAME="IDX5880"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>extra_linker_opts(Opts)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Opts</CODE> is the list of additional linker options that will be used during the linkage. <LI><EM>The following properties hold at call time:</EM> <CODE>Opts</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5881"></A> <A NAME="IDX5882"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>extra_linker_opts/2:</B> <DD><A NAME="IDX5883"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>extra_linker_opts(OsArch, Opts)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Opts</CODE> are the OS and architecture dependant additional linker options. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Opts</CODE> is an atom or a list of atoms. (<CODE>basic_props:atm_or_atm_list/1</CODE>) </UL> </DL> <P> <A NAME="IDX5884"></A> <A NAME="IDX5885"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_linker/1:</B> <DD><A NAME="IDX5886"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_linker(Linker)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Linker</CODE> is the linker to use in this file. When this option is used, the default (Ciao-provided) linker options are not used; those specified in <A NAME="IDX5887"></A> <CODE>extra_linker_options/1</CODE> are used instead. <LI><EM>The following properties hold at call time:</EM> <CODE>Linker</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <P> <A NAME="IDX5888"></A> <A NAME="IDX5889"></A> <DL> <DT><span class="define">DECLARATION:</span> <B>use_linker/2:</B> <DD><A NAME="IDX5890"></A> <P> <STRONG>Usage:</STRONG> :- <CODE>use_linker(OsArch, Linker)</CODE>. <UL> <LI><EM>Description:</EM> <CODE>Compiler</CODE> is the linker to use in this file when compiling for the architecture <CODE>OsArch</CODE>. The option management is the same as in <A NAME="IDX5891"></A> <CODE>use_compiler/2</CODE>. <LI><EM>The following properties hold at call time:</EM> <CODE>OsArch</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Linker</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <H2><A NAME="SEC527" HREF="ciao_toc.html#TOC527">Known bugs and planned improvements (<CODE>foreign_interface_properties</CODE>)</A></H2> <UL> <LI> The <CODE>size_of/3</CODE> property has an empty definition </UL> <P><HR><P> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_120.html">previous</A>, <A HREF="ciao_122.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. </BODY> </HTML>
