1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
<TITLE>Ports and Port Drivers</TITLE>
<SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="13"><!-- Empty --></A>
<H2>13 Ports and Port Drivers</H2>
<P>Examples of how to use ports and port drivers can be found in
<STRONG>Interoperability Tutorial</STRONG>. The BIFs mentioned are as usual
documented in <CODE>erlang(3)</CODE>.<A NAME="13.1"><!-- Empty --></A>
<H3>13.1 Ports</H3>
<P><STRONG>Ports</STRONG> provide the basic mechanism for communication
with the external world, from Erlang's point of view. They
provide a byte-oriented interface to an external program. When a
port has been created, Erlang can communicate with it by sending
and receiving lists of bytes, including binaries.
<P>The Erlang process which creates a port is said to be
the <STRONG>port owner</STRONG>, or the <STRONG>connected process</STRONG> of
the port. All communication to and from the port should go via
the port owner. If the port owner terminates, so will the port
(and the external program, if it is written correctly).
<P>The external program resides in another OS process. By default,
it should read from standard input (file descriptor 0) and write
to standard output (file descriptor 1). The external program
should terminate when the port is closed.<A NAME="13.2"><!-- Empty --></A>
<H3>13.2 Port Drivers</H3>
<P>It is also possible to write a driver in C according to certain
principles and dynamically link it to the Erlang runtime system.
The linked-in driver looks like a port from the Erlang
programmer's point of view and is called a <STRONG>port driver</STRONG>.
<P>
<TABLE CELLPADDING=4>
<TR>
<TD VALIGN=TOP><IMG ALT="Warning!" SRC="warning.gif"></TD>
<TD>
<P>An erroneous port driver will cause the entire Erlang runtime
system to leak memory, hang or crash. </TD>
</TR>
</TABLE>
<P>Port drivers are documented in <CODE>erl_driver(4)</CODE>,
<CODE>driver_entry(1)</CODE> and <CODE>erl_ddll(3)</CODE>.<A NAME="13.3"><!-- Empty --></A>
<H3>13.3 Port BIFs</H3>
<P>To create a port:
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Port Creation BIF.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>open_port(PortName, PortSettings</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Returns a port identifier <CODE>Port</CODE> as the result of
opening a new Erlang port. Messages can be sent to and
received from a port identifier, just like a pid. Port
identifiers can also be linked to or registered under a name
using <CODE>link/1</CODE> and <CODE>register/2</CODE>.
</TD>
</TR>
</TABLE>
</CENTER>
<P><CODE>PortName</CODE> is usually a tuple <CODE>{spawn,Command}</CODE>, where
the string <CODE>Command</CODE> is the name of the external program.
The external program runs outside the Erlang workspace unless a
port driver with the name <CODE>Command</CODE> is found. If found, that
driver is started.
<P><CODE>PortSettings</CODE> is a list of settings (options) for the port.
The list typically contains at least a tuple <CODE>{packet,N}</CODE>
which specifies that data sent between the port and the external
program are preceded by an N-byte length indicator. Valid values
for N are 1, 2 or 4. If binaries should be used instead of lists
of bytes, the option <CODE>binary</CODE> must be included.
<P>The port owner <CODE>Pid</CODE> can communicate with the port
<CODE>Port</CODE> by sending and receiving messages. (In fact, any
process can send the messages to the port, but the messages from
the port always go to the port owner).
<P>Below, <CODE>Data</CODE> must be an I/O list. An I/O list is a binary
or a (possibly deep) list of binaries or integers in the range
0..255.
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Messages Sent To a Port.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Pid,{command,Data}}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Sends <CODE>Data</CODE> to the port.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Pid,close}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Closes the port. Unless the port is already closed,
the port replies with <CODE>{Port,closed}</CODE> when all buffers
have been flushed and the port really closes.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Pid,{connect,NewPid}}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Sets the port owner of <CODE>Port</CODE> to <CODE>NewPid</CODE>.
Unless the port is already closed, the port replies with
<CODE>{Port,connected}</CODE> to the old port owner. Note that
the old port owner is still linked to the port, but the new
port owner is not.
</TD>
</TR>
</TABLE>
</CENTER>
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Messages Received From a Port.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Port,{data,Data}}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>Data</CODE> is received from the external program.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Port,closed}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Reply to <CODE>Port ! {Pid,close}</CODE>.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{Port,connected}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Reply to <CODE>Port ! {Pid,{connect,NewPid}}</CODE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{'EXIT',Port,Reason}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
If the port has terminated for some reason.
</TD>
</TR>
</TABLE>
</CENTER>
<P>Instead of sending and receiving messages, there are also a
number of BIFs that can be used. These can be called by any
process, not only the port owner.
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Port BIFs.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>port_command(Port,Data)</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Sends <CODE>Data</CODE> to the port.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>port_close(Port)</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Closes the port.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>port_connect(Port,NewPid)</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Sets the port owner of <CODE>Port</CODE> to <CODE>NewPid</CODE>.
The old port owner <CODE>Pid</CODE> stays linked to the port and
have to call <CODE>unlink(Port)</CODE> if this is not desired.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>erlang:port_info(Port,Item)</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Returns information as specified by <CODE>Item</CODE>.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>erlang:ports()</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Returns a list of all ports on the current node.
</TD>
</TR>
</TABLE>
</CENTER>
<P>There are some additional BIFs that only apply to port drivers:
<CODE>port_control/3</CODE> and <CODE>erlang:port_call/3</CODE>.<CENTER>
<HR>
<SMALL>
Copyright © 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
