File: clib.html

package info (click to toggle)
swi-prolog-packages 5.0.1-1
links: PTS
area: main
in suites: woody
size: 50,688 kB
ctags: 25,904
sloc: ansic: 195,096; perl: 91,425; cpp: 7,660; sh: 3,046; makefile: 2,750; yacc: 843; awk: 14; sed: 12
file content (709 lines) | stat: -rw-r--r-- 28,303 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>
<HEAD>
<TITLE>SWI-Prolog C-library</TITLE>
</HEAD>
<BODY BGCOLOR="white">
<BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<CENTER>

<H1>SWI-Prolog C-library</H1>

</CENTER>
<HR>
<CENTER>
<I>Jan Wielemaker <BR>
SWI, <BR>
University of Amsterdam <BR>
The Netherlands <BR>
E-mail: <A HREF="mailto:jan@swi.psy.uva.nl">jan@swi.psy.uva.nl</A></I>
</CENTER>
<HR>
</BLOCKQUOTE>
</BLOCKQUOTE>
</BLOCKQUOTE>
</BLOCKQUOTE>
<CENTER><H3>Abstract</H3></Center>
<TABLE WIDTH="90%" ALIGN=center BORDER=2 BGCOLOR="#f0f0f0"><TR><TD>
This document describes commonly used foreign language extensions to
<A HREF="http://www.swi.psy.uva.nl/projects/SWI-Prolog">SWI-Prolog</A> 
distributed as a package known under the name <EM>clib</EM>. The package 
defines a number of Prolog libraries with accompagnying foreign 
libraries.

<DL>

<P>
<DT><B><CODE>library(unix)</CODE></B><DD>
This library provides Unix process control using fork(), exec(), pipe(), 
etc.
<DT><B><CODE>library(cgi)</CODE></B><DD>
This library provides access to CGI form-data if Prolog is used for 
CGI-scripting.
<DT><B><CODE>library(crypt)</CODE></B><DD>
This library provides access to Unix password encryption.
<DT><B><CODE>library(mime)</CODE></B><DD>
This library decodes MIME messages.
<DT><B><CODE>library(socket)</CODE></B><DD>
This library provides access to TCP/IP communication.
</DL>

<P>Currently only <CODE>library(socket)</CODE> and <CODE>library(cgi)</CODE> 
are available on the default MS-Windows distribution. The <CODE>library(unix)</CODE> 
and
<CODE>library(crypt)</CODE> libraries can be used if the whole 
SWI-Prolog suite is compiled using <A HREF="http://www.cygwin.com">Cywin</A>.
</TABLE>

<H1><A NAME="document-contents">Table of Contents</A></H1>

<UL>
<LI><A HREF="#sec:1"><B>1 Introduction</B></A>
<LI><A HREF="#sec:2"><B>2 Unix Process manipulation library</B></A>
<LI><A HREF="#sec:3"><B>3 Socket library</B></A>
<UL>
<LI><A HREF="#sec:3.1">3.1 Server applications</A>
<LI><A HREF="#sec:3.2">3.2 Client applications</A>
</UL>
<LI><A HREF="#sec:4"><B>4 CGI Support library</B></A>
<UL>
<LI><A HREF="#sec:4.1">4.1 Some considerations</A>
</UL>
<LI><A HREF="#sec:5"><B>5 MIME decoding library</B></A>
<LI><A HREF="#sec:6"><B>6 Unix password encryption library</B></A>
<LI><A HREF="#sec:7"><B>7 Memory files</B></A>
<LI><A HREF="#sec:8"><B>8 Installation</B></A>
<UL>
<LI><A HREF="#sec:8.1">8.1 Unix systems</A>
</UL>
</UL>

<P>

<H2><A NAME="sec:1">1 Introduction</A></H2>

<P>Many useful facilities offered by one or more of the operating 
systems supported by SWI-Prolog are not supported by the SWI-Prolog 
kernel distribution. Including these would enlarge the <EM>footprint</EM> 
and complicate portability matters while supporting only a limited part 
of the user-community.

<P>This document describes <CODE>library(unix)</CODE> to deal with the 
Unix process API,
<CODE>library(socket)</CODE> to deal with inet-domain stream-sockets, <CODE>library(cgi)</CODE> 
to deal with getting CGI form-data if SWI-Prolog is used as a CGI 
scripting language and <CODE>library(crypt)</CODE> to provide access to 
Unix password encryption.

<H2><A NAME="sec:2">2 Unix Process manipulation library</A></H2>

<P>The <CODE>library(unix)</CODE> library provides the commonly used 
Unix primitives to deal with process management. These primitives are 
useful for many tasks, including server management, parallel 
computation, exploiting and controlling other processes, etc.

<P>The predicates are modelled closely after their native Unix 
counterparts. Higher-level primitives, especially to make this library 
portable to non-Unix systems are desirable. Using these primitives and 
considering that process manipulation is not a very time-critical 
operation we anticipate these libraries to be developed in Prolog.

<DL>

<P>
<DT><A NAME="fork/1"><STRONG>fork</STRONG>(<VAR>-Pid</VAR>)</A><DD>
Clone the current process into two branches. In the child, <VAR>Pid</VAR> 
is unified to <CODE>child</CODE>. In the original process, <VAR>Pid</VAR> 
is unified to the process identifier of the created child. Both parent 
and child are fully functional Prolog processes running the same 
program. The processes share open I/O streams that refer to Unix native 
streams, such as files, sockets and pipes. Data is not shared, though on 
most Unix systems data is initially shared and duplicated only if one of 
the programs attempts to modify the data.

<P>Unix <B>fork()</B> is the only way to create new processes and <A NAME="idx:fork2:1"></A><B>fork/2</B> 
is a simple direct interface to it.

<P>
<DT><A NAME="exec/1"><STRONG>exec</STRONG>(<VAR>+Command(...Args...)</VAR>)</A><DD>
Replace the running program by starting <VAR>Command</VAR> using the 
given commandline arguments. Each command-line argument must be atomic 
and is converted to a string before passed to the Unix call <B>execvp()</B>.

<P>Unix <B>exec()</B> is the only way to start an executable file 
executing. It is commonly used together with <A NAME="idx:fork1:2"></A><A HREF="#fork/1">fork/1</A>. 
For example to start <B>netscape</B> on an URL in the background, do:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

run_netscape(URL) :-
        (    fork(child),
             exec(netscape(URL))
        ;    true
        ).
</PRE>
</TABLE>

<P>Using this code, netscape remains part of the process-group of the 
invoking Prolog process and Prolog does not wait for netscape to 
terminate. The predicate <A NAME="idx:wait2:3"></A><A HREF="#wait/2">wait/2</A> 
allows waiting for a child, while
<A NAME="idx:detachIO0:4"></A><A HREF="#detach_IO/0">detach_IO/0</A> 
disconnects the child as a deamon process.

<P>
<DT><A NAME="wait/2"><STRONG>wait</STRONG>(<VAR>-Pid, -Status</VAR>)</A><DD>
Wait for a child to change status. Then report the child that changed 
status as well as the reason. <VAR>Status</VAR> is unified with
<CODE>exited(ExitCode)</CODE> if the child with pid <VAR>Pid</VAR> was 
terminated by calling <B>exit()</B> (Prolog <A NAME="idx:halt01:5"></A><B>halt/[0,1]</B>). <VAR>ExitCode</VAR> 
is the return=status. <VAR>Status</VAR> is unified with <CODE>signaled(Signal)</CODE> 
if the child died due to a software interrupt (see <A NAME="idx:kill2:6"></A><A HREF="#kill/2">kill/2</A>). <VAR>Signal</VAR> 
contains the signal number. Finally, if the process suspended execution 
due to a signal, <VAR>Status</VAR> is unified with <CODE>stopped(Signal)</CODE>.

<P>
<DT><A NAME="kill/2"><STRONG>kill</STRONG>(<VAR>+Pid, +Signal</VAR>)</A><DD>
Deliver a software interrupt to the process with identifier <VAR>Pid</VAR> 
using software-interrupt number <VAR>Signal</VAR>. See also <A NAME="idx:onsignal2:7"></A><B>on_signal/2</B>. 
The meaning of the signal numbers can be found in the Unix manual.<A NAME=back-to-note-1 HREF="index.html#note-1"> (1)</A>.

<P>
<DT><A NAME="pipe/2"><STRONG>pipe</STRONG>(<VAR>-InSream, -OutStream</VAR>)</A><DD>
Create a communication-pipe. This is normally used to make a child 
communicate to its parent. After <A NAME="idx:pipe2:8"></A><A HREF="#pipe/2">pipe/2</A>, 
the process is cloned and, depending on the desired direction, both 
processes close the end of the pipe they do not use. Then they use the 
remaining stream to communicate. Here is a simple example:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

:- use_module(library(unix)).

fork_demo(Result) :-
        pipe(Read, Write),
        fork(Pid),
        (   Pid == child
        -&gt;  close(Read),
            format(Write, '~q.~n',
                   [hello(world)]),
            flush_output(Write),
            halt
        ;   close(Write),
            read(Read, Result),
            close(Read)
        ).
</PRE>
</TABLE>

<P>
<DT><A NAME="dup/2"><STRONG>dup</STRONG>(<VAR>+FromStream, +ToStream</VAR>)</A><DD>
Interface to Unix dup2(), copying the underlying filedescriptor and thus 
making both streams point to the same underlying object. This is 
normally used together with <A NAME="idx:fork1:9"></A><A HREF="#fork/1">fork/1</A> 
and <A NAME="idx:pipe2:10"></A><A HREF="#pipe/2">pipe/2</A> to talk to 
an external program that is designed to communicate using standard I/O.

<P>Both <VAR>FromStream</VAR> and <VAR>ToStream</VAR> either refer to a 
Prolog stream or an integer descriptor number to refer directly to OS 
descriptors. See also <CODE>demo/pipe.pl</CODE> in the 
source-distribution of this package.

<P>
<DT><A NAME="detach_IO/0"><STRONG>detach_IO</STRONG></A><DD>
This predicate is intended to create Unix deamon-processes. It preforms 
two actions. First of all, the I/O streams <CODE>user_input</CODE>,
<CODE>user_output</CODE> and <CODE>user_error</CODE> are closed and 
rebound to a Prolog stream that returns end-of-file on any attempt to 
read and starts writing to a file named <CODE>/tmp/pl-out.pid</CODE> 
(where &lt;<VAR>pid</VAR>&gt; is the process-id of the calling Prolog) 
on any attempt to write. This file is opened only if there is data 
available. This is intended for debugging purposes.<A NAME=back-to-note-2 HREF="index.html#note-2"> (2)</A> 
Finally, the process is detached from the current process-group and its 
controlling terminal.
</DL>

<H2><A NAME="sec:3">3 Socket library</A></H2>

<P>The <CODE>library(socket)</CODE> library provides TCP inet-domain 
sockets from SWI-Prolog, both client and server-side communication. The 
interface of this library is very close to the Unix socket interface, 
also supported by the MS-Windows <EM>winsock</EM> API. Since SWI-Prolog 
4.0, XPCE is part of SWI-Prolog and offers . XPCE provides an 
event-driven interface to sockets, handling multiple open sockets in 
paralel.

<P>In the future we hope to provide a more high-level socket interface 
defined in Prolog and based on these primitives.

<DL>

<P>
<DT><A NAME="tcp_socket/1"><STRONG>tcp_socket</STRONG>(<VAR>-SocketId</VAR>)</A><DD>
Creates an <CODE>INET</CODE>-domain stream-socket and unifies an 
identifier to it with <VAR>SocketId</VAR>. On MS-Windows, if the socket 
library is not yet initialised, this will also initialise the library.

<P>
<DT><A NAME="tcp_close_socket/1"><STRONG>tcp_close_socket</STRONG>(<VAR>+SocketId</VAR>)</A><DD>
Closes the indicated socket, making <VAR>SocketId</VAR> invalid. 
Normally, sockets are closed by closing both stream handles returned by
<A NAME="idx:opensocket3:11"></A><B>open_socket/3</B>. There are two 
cases where <A NAME="idx:tcpclosesocket1:12"></A><A HREF="#tcp_close_socket/1">tcp_close_socket/1</A> 
is used because there are no stream-handles:

<P>
<UL>
<LI>After <A NAME="idx:tcpaccept3:13"></A><A HREF="#tcp_accept/3">tcp_accept/3</A>, 
the server does a <A NAME="idx:fork1:14"></A><A HREF="#fork/1">fork/1</A> 
to handle the client in a sub-process. In this case the accepted socket 
is not longer needed from the main server and must be discarded using <A NAME="idx:tcpclosesocket1:15"></A><A HREF="#tcp_close_socket/1">tcp_close_socket/1</A>.
<LI>If, after discovering the connecting client with <A NAME="idx:tcpaccept3:16"></A><A HREF="#tcp_accept/3">tcp_accept/3</A>, 
the server does not want to accept the connection, it should discard the 
accepted socket immediately using <A NAME="idx:tcpclosesocket1:17"></A><A HREF="#tcp_close_socket/1">tcp_close_socket/1</A>.
</UL>

<P>
<DT><A NAME="tcp_open_socket/3"><STRONG>tcp_open_socket</STRONG>(<VAR>+SocketId, 
-InStream, -OutStream</VAR>)</A><DD>
Open two SWI-Prolog I/O-streams, one to deal with input from the socket 
and one with output to the socket. If <A NAME="idx:tcpbind2:18"></A><A HREF="#tcp_bind/2">tcp_bind/2</A> 
has been called on the socket. <VAR>OutSream</VAR> is useless and will 
not be created. After closing both <VAR>InStream</VAR> and <VAR>OutSream</VAR>, 
the socket itself is discarded.

<P>
<DT><A NAME="tcp_bind/2"><STRONG>tcp_bind</STRONG>(<VAR>+Socket, +Port</VAR>)</A><DD>
Bind the socket to <VAR>Port</VAR> on the current machine. This 
operation, together with <A NAME="idx:tcplisten2:19"></A><A HREF="#tcp_listen/2">tcp_listen/2</A> 
and <A NAME="idx:tcpaccept3:20"></A><A HREF="#tcp_accept/3">tcp_accept/3</A> 
implement the <EM>server</EM>-side of the socket interface.

<P>
<DT><A NAME="tcp_listen/2"><STRONG>tcp_listen</STRONG>(<VAR>+Socket, 
+Backlog</VAR>)</A><DD>
Tells, after <A NAME="idx:tcpbind2:21"></A><A HREF="#tcp_bind/2">tcp_bind/2</A>, 
the socket to listen for incoming requests for connections. <VAR>Backlog</VAR> 
indicates how many pending connection requests are allowed. Pending 
requests are requests that are not yet acknowledged using <A NAME="idx:tcpaccept3:22"></A><A HREF="#tcp_accept/3">tcp_accept/3</A>. 
If the indicated number is exceeded, the requesting client will be 
signalled that the service is currently not available. A suggested 
default value is 5.

<P>
<DT><A NAME="tcp_accept/3"><STRONG>tcp_accept</STRONG>(<VAR>+Socket, 
-Slave, -Peer</VAR>)</A><DD>
This predicate waits on a server socket for a connection request by a 
client. On success, it creates a new socket for the client and binds the 
identifier to <VAR>Slave</VAR>. <VAR>Peer</VAR> is bound to the 
IP-address of the client.

<P>
<DT><A NAME="tcp_connect/+Socket. +Host:+Port"><STRONG>tcp_connect</STRONG>(<VAR>+Socket. 
+Host:+Port</VAR>)</A><DD>
lient-interface to connect a socket to a given <VAR>Port</VAR> on a 
given
<VAR>Host</VAR>. After successful completion, <A NAME="idx:tcpopensocket3:23"></A><A HREF="#tcp_open_socket/3">tcp_open_socket/3</A> 
can be used to create I/O-Streams to the remote socket.

<P>
<DT><A NAME="tcp_setopt/2"><STRONG>tcp_setopt</STRONG>(<VAR>+Socket, 
+Option</VAR>)</A><DD>
Interface to setsockopt(), setting options for the socket. Currently the 
only defined option is <CODE>reuseaddr</CODE>, which allows servers to 
reuse a port without the system being completely sure the port is no 
longer in use.

<P>
<DT><A NAME="tcp_fcntl/3"><STRONG>tcp_fcntl</STRONG>(<VAR>+Stream, 
+Action, ?Argument</VAR>)</A><DD>
Interface to the Unix <B>fcntl()</B> call. Currently only suitable to 
deal switch stream to non-blocking mode using:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

        ...
        tcp_fcntlStream, setfl. nonblock),
        ...
</PRE>
</TABLE>

<P>As of SWI-Prolog 3.2.4, handling of non-blocking stream is supported. 
An attempt to read from a non-blocking stream returns -1 (or
<CODE>end_of_file</CODE> for <A NAME="idx:read1:24"></A><B>read/1</B>), 
but <A NAME="idx:atendofstream1:25"></A><B>at_end_of_stream/1</B> fails. 
On actual end-of-input, <A NAME="idx:atendofstream1:26"></A><B>at_end_of_stream/1</B> 
succeeds.

<P>
<DT><A NAME="tcp_host_to_address/2"><STRONG>tcp_host_to_address</STRONG>(<VAR>?HostName, 
?Address</VAR>)</A><DD>
Translate between a machines host-name and it's (IP-)address. If
<VAR>HostName</VAR> is an atom, it is resolved using
<B>gethostbyname()</B> and the IP-number is unified to <VAR>Address</VAR> 
using a term of the format <CODE>ip(Byte1, Byte2, Byte3, Byte4)</CODE>. 
Otherwise, if <VAR>Address</VAR> is bound to a ip/4 term, it is resolved 
by <B>gethostbyaddr()</B> and the canonical hostname is unified with <VAR>HostName</VAR>.

<P>
<DT><A NAME="gethostname/1"><STRONG>gethostname</STRONG>(<VAR>-Hostname</VAR>)</A><DD>
Return the official fully qualified name of this host. This is achieved 
by calling gethostname() followed by gethostbyname() and return the 
official name of the host (<CODE>h_name</CODE>) of the structure 
returned by the latter function.
</DL>

<H3><A NAME="sec:3.1">3.1 Server applications</A></H3>

<P>The typical sequence for generating a server application is defined 
below:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

create_server(Port) :-
        tcp_socket(Socket),
        tcp_bind(Socket, Port),
        tcp_listen(Socket, 5),
        tcp_open_socket(Socket, AcceptFd, _),
        &lt;dispatch&gt;
</PRE>
</TABLE>

<P>There are various options for &lt;<VAR>dispatch</VAR>&gt;. One is to 
keep track of active clients and server-sockets using <A NAME="idx:waitforinput3:27"></A><B>wait_for_input/3</B>. 
If input arrives at a server socket, use <A NAME="idx:tcpaccept3:28"></A><A HREF="#tcp_accept/3">tcp_accept/3</A> 
and add the new connection to the active clients. Otherwise deal with 
the input from the client. Another is to use (Unix) <A NAME="idx:fork1:29"></A><A HREF="#fork/1">fork/1</A> 
to deal with the client in a separate process.

<P>Using <A NAME="idx:fork1:30"></A><A HREF="#fork/1">fork/1</A>, &lt;<VAR>dispatch</VAR>&gt; 
may be implemented as:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

dispatch(AcceptFd) :-
        tcp_accept(AcceptFd, Socket, _Peer),
        fork(Pid)
        (   Pid == child
        -&gt;  tcp_open_socket(Socket, In, Out),
            handle_service(In, Out),
            close(In),
            close(Out),
            halt
        ;   tcp_close_socket(Socket)
        ),
        dispatch(AcceptFd).
</PRE>
</TABLE>

<H3><A NAME="sec:3.2">3.2 Client applications</A></H3>

<P>The skeleton for client-communication is given below.

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

create_client(Host, Port) :-
        tcp_socket(Socket),
        tcp_connect(Socket, Host:Port),
        tcp_open_socket(Socket, ReadFd, WriteFd),
        &lt;handle I/O using the two streams&gt;
        close(ReadFd),
        close(WriteFd).
</PRE>
</TABLE>

<P>To deal with timeouts and multiple connections, <A NAME="idx:waitforinput3:31"></A><B>wait_for_input/3</B> 
and/or non-blocking streams (see <A NAME="idx:tcpfcntl3:32"></A><A HREF="#tcp_fcntl/3">tcp_fcntl/3</A>) 
can be used.

<H2><A NAME="sec:4">4 CGI Support library</A></H2>

<P>This is currently a very simple library, providing support for 
obtaining the form-data for a CGI script:

<DL>

<P>
<DT><A NAME="cgi_get_form/1"><STRONG>cgi_get_form</STRONG>(<VAR>-Form</VAR>)</A><DD>
Decodes standard input and the environment variables to obtain a list of 
arguments passed to the CGI script. This predicate both deals with the 
CGI <B>GET</B> method as well as the <B>POST</B> method. If the data 
cannot be obtained, an <CODE>existence_error</CODE> exception is raised.
</DL>

<P>Below is a very simple CGI script that prints the passed parameters. 
To test it, compile this program using the command below, copy it to 
your cgi-bin directory (or make it otherwise known as a CGI-script) and 
make the query <CODE>http://myhost.mydomain/cgi-bin/cgidemo?hello=world</CODE>

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

% pl -o cgidemo --goal=main --toplevel=halt -c cgidemo.pl
</PRE>
</TABLE>

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

:- use_module(library(cgi)).

main :-
        cgi_get_form(Arguments),
        format('Content-type: text/html~n~n', []),
        format('&lt;HTML&gt;~n', []),
        format('&lt;HEAD&gt;~n', []),
        format('&lt;TITLE&gt;Simple SWI-Prolog CGI script&lt;/TITLE&gt;~n', []),
        format('&lt;/HEAD&gt;~n~n', []),
        format('&lt;BODY&gt;~n', []),
        format('&lt;P&gt;', []),
        print_args(Arguments),
        format('&lt;BODY&gt;~n&lt;/HTML&gt;~n', []).

print_args([]).
print_args([A0|T]) :-
        A0 =.. [Name, Value],
        format('&lt;B&gt;~w&lt;/B&gt;=&lt;EM&gt;~w&lt;/EM&gt;&lt;BR&gt;~n', [Name, Value]),
        print_args(T).
</PRE>
</TABLE>

<H3><A NAME="sec:4.1">4.1 Some considerations</A></H3>

<P>Printing an HTML document using <A NAME="idx:format2:33"></A><B>format/2</B> 
is not really a neat way of producing HTML. A high-level alternative is 
provided by
<CODE>library(http/html_write)</CODE> from the XPCE package.

<H2><A NAME="sec:5">5 MIME decoding library</A></H2>

<P>MIME (Multipurpose Internet Mail Extensions) is a format for 
serializing multiple typed data objects. It was designed for E-mail, but 
it is also used for other applications such packaging multiple values 
using the HTTP POST request on web-servers. Double Precision, Inc. has 
produced the C-libraries rfc822 (mail) and rfc2045 (MIME) for decoding 
and manipulating MIME messages. The <CODE>library(mime)</CODE> library 
is a Prolog wrapper around the rfc2045 library for deconding MIME 
messages.

<P>The general name `mime' is used for this library as it is anticipated 
to add MIME-creation functionality to this message.

<P>Currently the mime library defines one predicate:

<DL>

<P>
<DT><A NAME="mime_parse/2"><STRONG>mime_parse</STRONG>(<VAR>Data, Parsed</VAR>)</A><DD>
Parse <VAR>Data</VAR> and unify the result to <VAR>Parsed</VAR>. <VAR>Data</VAR> 
is one of:

<DL>

<P>
<DT><STRONG>stream</STRONG>(<VAR>Stream</VAR>)<DD>
Parse the data from <VAR>Stream</VAR> upto the end-of-file.

<P>
<DT><STRONG>stream</STRONG>(<VAR>Stream, Length</VAR>)<DD>
Parse a maximum of <VAR>Length</VAR> characters from <VAR>Stream</VAR> 
or upto the end-of-file, whichever comes first.

<P>
<DT><STRONG><VAR>Text</VAR></STRONG><DD>
Atoms, strings, code- and character lists are treated as valid sources 
of data.
</DL>

<P><VAR>Parsed</VAR> is a tree structure of <CODE>mime(Attributes, Data, 
PartList)</CODE> terms. Currently either <VAR>Data</VAR> is the empty 
atom or <VAR>PartList</VAR> is an empty list.<A NAME=back-to-note-3 HREF="index.html#note-3"> (3)</A>
<VAR>Data</VAR> is an atom holding the message data. The library 
automatically decodes <EM>base64</EM> and <EM>quoted-printable</EM> 
messages. See also the <CODE>transfer_encoding</CODE> attribute below.

<P><VAR>PartList</VAR> is a list of <B>mime(3)</B> terms. <VAR>Attributes</VAR> 
is a list holding a subset of the following arguments. For details 
please consult the RFC2045 document.

<DL>

<P>
<DT><STRONG>type</STRONG>(<VAR>Atom</VAR>)<DD>
Denotes the Content-Type, how the <VAR>Data</VAR> should be interpreted.

<P>
<DT><STRONG>transfer_encoding</STRONG>(<VAR>Atom</VAR>)<DD>
How the <VAR>Data</VAR> was encoded. This is not very interesting as the 
library decodes the content of the message.

<P>
<DT><STRONG>character_set</STRONG>(<VAR>Atom</VAR>)<DD>
The character set used for text data. Note that SWI-Prolog's 
capabilities for character-set handling are limited.

<P>
<DT><STRONG>language</STRONG>(<VAR>Atom</VAR>)<DD>
Language in which the text-data is written.

<P>
<DT><STRONG>id</STRONG>(<VAR>Atom</VAR>)<DD>
Identifier of the message-part.

<P>
<DT><STRONG>description</STRONG>(<VAR>Atom</VAR>)<DD>
Descrptive text for the <VAR>Data</VAR>.

<P>
<DT><STRONG>disposition</STRONG>(<VAR>Atom</VAR>)<DD>
Where the data comes from. The current library only deals with `inline' 
data.

<P>
<DT><STRONG>name</STRONG>(<VAR>Atom</VAR>)<DD>
Name of the part.

<P>
<DT><STRONG>filename</STRONG>(<VAR>Atom</VAR>)<DD>
Name of the file the data should be stored in.
</DL>

</DL>

<P><B>NOTE</B> This library is only built and installed if the maildrop 
libraries are installed on your system.

<H2><A NAME="sec:6">6 Unix password encryption library</A></H2>

<P>The <CODE>library(crypt)</CODE> library defines <A NAME="idx:crypt2:34"></A><A HREF="#crypt/2">crypt/2</A> 
for encrypting and testing Unix passwords:

<DL>

<P>
<DT><A NAME="crypt/2"><STRONG>crypt</STRONG>(<VAR>+Plain, ?Encrypted</VAR>)</A><DD>
This predicate can be used in three modes. If <VAR>Encrypted</VAR> is 
unbound, it will be unified to a string (list of character-codes) 
holding a random encryption of <VAR>Plain</VAR>. If <VAR>Encrypted</VAR> 
is bound to a list holding 2 characters and an unbound tail, these two 
character are used for the <EM>salt</EM> of the encryption. Finally, if <VAR>Encrypted</VAR> 
is instantiated to an encrypted password the predicate succeeds iff <VAR>Encrypted</VAR> 
is a valid encryption of
<VAR>Plain</VAR>.

<P><VAR>Plain</VAR> is either an atom, SWI-Prolog string, list of 
characters or list of character-codes. It is not advised to use atoms, 
as this implies the password will be available from the Prolog heap as a 
defined atom.
</DL>

<H2><A NAME="sec:7">7 Memory files</A></H2>

<P>The <CODE>library(memfile)</CODE> provides an alternative to 
temporary files, intended for temporary buffering of data. Memory files 
in general are faster than temporary files and do not suffer from 
security riscs or naming conflicts associated with temporary-file 
management. They do assume proper memory management by the hosting OS 
and cannot be used to pass data to external processes using a file-name.

<P>There is no limit to the number of memory streams, nor the size of 
them. However, memory-streams cannot have multiple streams at the same 
time (i.e. cannot be opened for reading and writing at the same time).

<P>These predicates are first of all intended for building higher-level 
primitives. See also <A NAME="idx:sformat3:35"></A><B>sformat/3</B>, <A NAME="idx:atomtoterm3:36"></A><B>atom_to_term/3</B>, <A NAME="idx:termtoatom2:37"></A><B>term_to_atom/2</B> 
and the XPCE primitive <A NAME="idx:pceopen3:38"></A><B>pce_open/3</B>.

<DL>

<P>
<DT><A NAME="new_memory_file/-Handle"><STRONG>new_memory_file</STRONG>(<VAR>-Handle</VAR>)</A><DD>
reate a new memory file and return a unique opaque handle to it.

<P>
<DT><A NAME="free_memory_file/+Handle"><STRONG>free_memory_file</STRONG>(<VAR>+Handle</VAR>)</A><DD>
iscard the memory file and its contents. If the file is open it is first 
closed.

<P>
<DT><A NAME="open_memory_file/+Handle, +Mode, -Stream"><STRONG>open_memory_file</STRONG>(<VAR>+Handle, 
+Mode, -Stream</VAR>)</A><DD>
pen the memory-file. <VAR>Mode</VAR> is currently one of <CODE>read</CODE> 
or <CODE>write</CODE>. The resulting handling is closed using <A NAME="idx:close1:39"></A><B>close/1</B>.

<P>
<DT><A NAME="size_memory_file/+Handle, -Bytes"><STRONG>size_memory_file</STRONG>(<VAR>+Handle, 
-Bytes</VAR>)</A><DD>
eturn the content-length of the memory-file it <VAR>Bytes</VAR>. The 
file should be closed and contain data.

<P>
<DT><A NAME="atom_to_memory_file/+Atom, -Handle"><STRONG>atom_to_memory_file</STRONG>(<VAR>+Atom, 
-Handle</VAR>)</A><DD>
urn an atom into a read-only memory-file containing the (shared) 
characters of the atom. Opening this memory-file in mode <CODE>write</CODE> 
yields a permission error.

<P>
<DT><A NAME="memory_file_to_atom/+Handle, -Atom"><STRONG>memory_file_to_atom</STRONG>(<VAR>+Handle, 
-Atom</VAR>)</A><DD>
eturn the content of the memory-file in <VAR>Atom</VAR>.

<P>
<DT><A NAME="memory_file_to_codes/+Handle, -Codes"><STRONG>memory_file_to_codes</STRONG>(<VAR>+Handle, 
-Codes</VAR>)</A><DD>
eturn the content of the memory-file as a list of character-codes in <VAR>Codes</VAR>.
</DL>

<H2><A NAME="sec:8">8 Installation</A></H2>

<H3><A NAME="sec:8.1">8.1 Unix systems</A></H3>

<P>Installation on Unix system uses the commonly found <EM>configure</EM>,
<EM>make</EM> and <EM>make install</EM> sequence. SWI-Prolog should be 
installed before building this package. If SWI-Prolog is not installed 
as <B>pl</B>, the environment variable <CODE>PL</CODE> must be set to 
the name of the SWI-Prolog executable. Installation is now accomplished 
using:

<P><P><TABLE WIDTH="90%" ALIGN=center BORDER=6 BGCOLOR="#e0e0e0"><TR><TD NOWRAP>
<PRE>

% ./configure
% make
% make install
</PRE>
</TABLE>

<P>This installs the foreign libraries in <CODE>$PLBASE/lib/$PLARCH</CODE> 
and the Prolog library files in <CODE>$PLBASE/library</CODE>, where
<CODE>$PLBASE</CODE> refers to the SWI-Prolog `home-directory'.

<H1><A NAME="document-notes">Footnotes</A></H1>

<DL>

<P>
<DT><A NAME=note-1 HREF="index.html#back-to-note-1">note-1</A><DD>
<A NAME="idx:kill2:40"></A><A HREF="#kill/2">kill/2</A> should support 
interrupt-names as well
<DT><A NAME=note-2 HREF="index.html#back-to-note-2">note-2</A><DD>
More subtle handling of I/O, especially for debugging is required: 
communicate with the syslog deamon and optionally start a debugging 
dialog on a newly created (X-)terminal should be considered.
<DT><A NAME=note-3 HREF="index.html#back-to-note-3">note-3</A><DD>
It is unclear to me whether a MIME note can contain a mixture of content 
and parts, but I believe the answer is `no'.
</DL>

</BODY></HTML>