<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Ports and Port Drivers</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.9.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 5.9.3.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#id73748">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#id66106">Prerequisites</a></li>
<li title="Document Conventions"><a href="introduction.html#id67296">Document Conventions</a></li>
<li title="Complete List of BIFs"><a href="introduction.html#id68121">Complete List of BIFs</a></li>
<li title="Reserved Words"><a href="introduction.html#id60679">Reserved Words</a></li>
<li title="Character Set"><a href="introduction.html#id61758">Character Set</a></li>
</ul>
</li>
<li id="no" title="Data Types" expanded="false">Data Types<ul>
<li><a href="data_types.html">
Top of chapter
</a></li>
<li title="Terms"><a href="data_types.html#id63330">Terms</a></li>
<li title="Number"><a href="data_types.html#id68697">Number</a></li>
<li title="Atom"><a href="data_types.html#id62285">Atom</a></li>
<li title="Bit Strings and Binaries"><a href="data_types.html#id68011">Bit Strings and Binaries</a></li>
<li title="Reference"><a href="data_types.html#id58120">Reference</a></li>
<li title="Fun"><a href="data_types.html#id67499">Fun</a></li>
<li title="Port Identifier"><a href="data_types.html#id69290">Port Identifier</a></li>
<li title="Pid"><a href="data_types.html#id60853">Pid</a></li>
<li title="Tuple"><a href="data_types.html#id73719">Tuple</a></li>
<li title="List"><a href="data_types.html#id73198">List</a></li>
<li title="String"><a href="data_types.html#id68626">String</a></li>
<li title="Record"><a href="data_types.html#id65682">Record</a></li>
<li title="Boolean"><a href="data_types.html#id67471">Boolean</a></li>
<li title="Escape Sequences"><a href="data_types.html#id73885">Escape Sequences</a></li>
<li title="Type Conversions"><a href="data_types.html#id69219">Type Conversions</a></li>
</ul>
</li>
<li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul>
<li><a href="patterns.html">
Top of chapter
</a></li>
<li title="Pattern Matching"><a href="patterns.html#id68202">Pattern Matching</a></li>
</ul>
</li>
<li id="no" title="Modules" expanded="false">Modules<ul>
<li><a href="modules.html">
Top of chapter
</a></li>
<li title="Module Syntax"><a href="modules.html#id68326">Module Syntax</a></li>
<li title="Module Attributes"><a href="modules.html#id68358">Module Attributes</a></li>
<li title="Comments"><a href="modules.html#id74337">Comments</a></li>
<li title="The module_info/0 and module_info/1 functions"><a href="modules.html#id74350">The module_info/0 and module_info/1 functions</a></li>
</ul>
</li>
<li id="no" title="Functions" expanded="false">Functions<ul>
<li><a href="functions.html">
Top of chapter
</a></li>
<li title="Function Declaration Syntax"><a href="functions.html#id74609">Function Declaration Syntax</a></li>
<li title="Function Evaluation"><a href="functions.html#id74724">Function Evaluation</a></li>
<li title="Tail recursion"><a href="functions.html#id74875">Tail recursion</a></li>
<li title="Built-In Functions, BIFs"><a href="functions.html#id74908">Built-In Functions, BIFs</a></li>
</ul>
</li>
<li id="no" title="Types and Function Specifications" expanded="false">Types and Function Specifications<ul>
<li><a href="typespec.html">
Top of chapter
</a></li>
<li title="Introduction of Types"><a href="typespec.html#id75024">Introduction of Types</a></li>
<li title="Types and their Syntax"><a href="typespec.html#id75072">Types and their Syntax</a></li>
<li title="Type declarations of user-defined types"><a href="typespec.html#id75688">Type declarations of user-defined types</a></li>
<li title="Type information in record declarations"><a href="typespec.html#id75770">Type information in record declarations</a></li>
<li title="Specifications for functions"><a href="typespec.html#id75847">Specifications for functions</a></li>
</ul>
</li>
<li id="no" title="Expressions" expanded="false">Expressions<ul>
<li><a href="expressions.html">
Top of chapter
</a></li>
<li title="Expression Evaluation"><a href="expressions.html#id76067">Expression Evaluation</a></li>
<li title="Terms"><a href="expressions.html#id76110">Terms</a></li>
<li title="Variables"><a href="expressions.html#id76122">Variables</a></li>
<li title="Patterns"><a href="expressions.html#id76253">Patterns</a></li>
<li title="Match"><a href="expressions.html#id76372">Match</a></li>
<li title="Function Calls"><a href="expressions.html#id76431">Function Calls</a></li>
<li title="If"><a href="expressions.html#id76631">If</a></li>
<li title="Case"><a href="expressions.html#id76696">Case</a></li>
<li title="Send"><a href="expressions.html#id76761">Send</a></li>
<li title="Receive"><a href="expressions.html#id76844">Receive</a></li>
<li title="Term Comparisons"><a href="expressions.html#id77009">Term Comparisons</a></li>
<li title="Arithmetic Expressions"><a href="expressions.html#id77270">Arithmetic Expressions</a></li>
<li title="Boolean Expressions"><a href="expressions.html#id77776">Boolean Expressions</a></li>
<li title="Short-Circuit Expressions"><a href="expressions.html#id77931">Short-Circuit Expressions</a></li>
<li title="List Operations"><a href="expressions.html#id78047">List Operations</a></li>
<li title="Bit Syntax Expressions"><a href="expressions.html#id78116">Bit Syntax Expressions</a></li>
<li title="Fun Expressions"><a href="expressions.html#id78658">Fun Expressions</a></li>
<li title="Catch and Throw"><a href="expressions.html#id78840">Catch and Throw</a></li>
<li title="Try"><a href="expressions.html#id78986">Try</a></li>
<li title="Parenthesized Expressions"><a href="expressions.html#id79344">Parenthesized Expressions</a></li>
<li title="Block Expressions"><a href="expressions.html#id79376">Block Expressions</a></li>
<li title="List Comprehensions"><a href="expressions.html#id79401">List Comprehensions</a></li>
<li title="Bit String Comprehensions"><a href="expressions.html#id79541">Bit String Comprehensions</a></li>
<li title="Guard Sequences"><a href="expressions.html#id79673">Guard Sequences</a></li>
<li title="Operator Precedence"><a href="expressions.html#id80211">Operator Precedence</a></li>
</ul>
</li>
<li id="no" title="The Preprocessor" expanded="false">The Preprocessor<ul>
<li><a href="macros.html">
Top of chapter
</a></li>
<li title="File Inclusion"><a href="macros.html#id80530">File Inclusion</a></li>
<li title="Defining and Using Macros"><a href="macros.html#id80659">Defining and Using Macros</a></li>
<li title="Predefined Macros"><a href="macros.html#id80782">Predefined Macros</a></li>
<li title="Macros Overloading"><a href="macros.html#id80850">Macros Overloading</a></li>
<li title="Flow Control in Macros"><a href="macros.html#id80919">Flow Control in Macros</a></li>
<li title="Stringifying Macro Arguments"><a href="macros.html#id81056">Stringifying Macro Arguments</a></li>
</ul>
</li>
<li id="no" title="Records" expanded="false">Records<ul>
<li><a href="records.html">
Top of chapter
</a></li>
<li title="Defining Records"><a href="records.html#id81178">Defining Records</a></li>
<li title="Creating Records"><a href="records.html#id81209">Creating Records</a></li>
<li title="Accessing Record Fields"><a href="records.html#id81264">Accessing Record Fields</a></li>
<li title="Updating Records"><a href="records.html#id81303">Updating Records</a></li>
<li title="Records in Guards"><a href="records.html#id81336">Records in Guards</a></li>
<li title="Records in Patterns"><a href="records.html#id81368">Records in Patterns</a></li>
<li title="Nested records"><a href="records.html#id81395">Nested records</a></li>
<li title="Internal Representation of Records"><a href="records.html#id81430">Internal Representation of Records</a></li>
</ul>
</li>
<li id="no" title="Errors and Error Handling" expanded="false">Errors and Error Handling<ul>
<li><a href="errors.html">
Top of chapter
</a></li>
<li title="Terminology"><a href="errors.html#id81550">Terminology</a></li>
<li title="Exceptions"><a href="errors.html#id81678">Exceptions</a></li>
<li title="Handling of Run-Time Errors in Erlang"><a href="errors.html#id81851">Handling of Run-Time Errors in Erlang</a></li>
<li title="Exit Reasons"><a href="errors.html#id81913">Exit Reasons</a></li>
</ul>
</li>
<li id="no" title="Processes" expanded="false">Processes<ul>
<li><a href="processes.html">
Top of chapter
</a></li>
<li title="Processes"><a href="processes.html#id82387">Processes</a></li>
<li title="Process Creation"><a href="processes.html#id82400">Process Creation</a></li>
<li title="Registered Processes"><a href="processes.html#id82449">Registered Processes</a></li>
<li title="Process Termination"><a href="processes.html#id82560">Process Termination</a></li>
<li title="Message Sending"><a href="processes.html#id82650">Message Sending</a></li>
<li title="Links"><a href="processes.html#id82679">Links</a></li>
<li title="Error Handling"><a href="processes.html#id82744">Error Handling</a></li>
<li title="Monitors"><a href="processes.html#id82854">Monitors</a></li>
<li title="Process Dictionary"><a href="processes.html#id82946">Process Dictionary</a></li>
</ul>
</li>
<li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul>
<li><a href="distributed.html">
Top of chapter
</a></li>
<li title="Distributed Erlang System"><a href="distributed.html#id83013">Distributed Erlang System</a></li>
<li title="Nodes"><a href="distributed.html#id83044">Nodes</a></li>
<li title="Node Connections"><a href="distributed.html#id83114">Node Connections</a></li>
<li title="epmd"><a href="distributed.html#id83164">epmd</a></li>
<li title="Hidden Nodes"><a href="distributed.html#id83184">Hidden Nodes</a></li>
<li title="C Nodes"><a href="distributed.html#id83230">C Nodes</a></li>
<li title="Security"><a href="distributed.html#id83254">Security</a></li>
<li title="Distribution BIFs"><a href="distributed.html#id83364">Distribution BIFs</a></li>
<li title="Distribution Command Line Flags"><a href="distributed.html#id83662">Distribution Command Line Flags</a></li>
<li title="Distribution Modules"><a href="distributed.html#id83799">Distribution Modules</a></li>
</ul>
</li>
<li id="no" title="Compilation and Code Loading" expanded="false">Compilation and Code Loading<ul>
<li><a href="code_loading.html">
Top of chapter
</a></li>
<li title="Compilation"><a href="code_loading.html#id84002">Compilation</a></li>
<li title="Code Loading"><a href="code_loading.html#id84112">Code Loading</a></li>
<li title="Code Replacement"><a href="code_loading.html#id84159">Code Replacement</a></li>
<li title="Running a function when a module is loaded"><a href="code_loading.html#id84234">Running a function when a module is loaded</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Ports and Port Drivers" expanded="true">Ports and Port Drivers<ul>
<li><a href="ports.html">
Top of chapter
</a></li>
<li title="Ports"><a href="ports.html#id84374">Ports</a></li>
<li title="Port Drivers"><a href="ports.html#id84409">Port Drivers</a></li>
<li title="Port BIFs"><a href="ports.html#id84449">Port BIFs</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>14 Ports and Port Drivers</h1>
<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 <span class="code">erlang(3)</span>.</p>
<h3><a name="id84374">14.1
Ports</a></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>
<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>
<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.</p>
<h3><a name="id84409">14.2
Port Drivers</a></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>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<p>An erroneous port driver will cause the entire Erlang runtime
system to leak memory, hang or crash.</p>
</p></div>
</div>
<p>Port drivers are documented in <span class="code">erl_driver(4)</span>,
<span class="code">driver_entry(1)</span> and <span class="code">erl_ddll(3)</span>.</p>
<h3><a name="id84449">14.3
Port BIFs</a></h3>
<p>To create a port:</p>
<table border="1" cellpadding="2" cellspacing="0"><tr>
<td align="left" valign="middle"><span class="code">open_port(PortName, PortSettings</span></td>
<td align="left" valign="middle">Returns a port identifier <span class="code">Port</span>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 <span class="code">link/1</span>and <span class="code">register/2</span>.</td>
</tr></table>
<em>Table
14.1:
Port Creation BIF.</em>
<p><span class="code">PortName</span> is usually a tuple <span class="code">{spawn,Command}</span>, where
the string <span class="code">Command</span> is the name of the external program.
The external program runs outside the Erlang workspace unless a
port driver with the name <span class="code">Command</span> is found. If found, that
driver is started.</p>
<p><span class="code">PortSettings</span> is a list of settings (options) for the port.
The list typically contains at least a tuple <span class="code">{packet,N}</span>
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 <span class="code">binary</span> must be included.</p>
<p>The port owner <span class="code">Pid</span> can communicate with the port
<span class="code">Port</span> 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>
<p>Below, <span class="code">Data</span> 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>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><span class="code">{Pid,{command,Data}}</span></td>
<td align="left" valign="middle">Sends <span class="code">Data</span>to the port.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{Pid,close}</span></td>
<td align="left" valign="middle">Closes the port. Unless the port is already closed, the port replies with <span class="code">{Port,closed}</span>when all buffers have been flushed and the port really closes.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{Pid,{connect,NewPid}}</span></td>
<td align="left" valign="middle">Sets the port owner of <span class="code">Port</span>to <span class="code">NewPid</span>. Unless the port is already closed, the port replies with<span class="code">{Port,connected}</span>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>
<em>Table
14.2:
Messages Sent To a Port.</em>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><span class="code">{Port,{data,Data}}</span></td>
<td align="left" valign="middle">
<span class="code">Data</span>is received from the external program.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{Port,closed}</span></td>
<td align="left" valign="middle">Reply to <span class="code">Port ! {Pid,close}</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{Port,connected}</span></td>
<td align="left" valign="middle">Reply to <span class="code">Port ! {Pid,{connect,NewPid}}</span>
</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{'EXIT',Port,Reason}</span></td>
<td align="left" valign="middle">If the port has terminated for some reason.</td>
</tr>
</table>
<em>Table
14.3:
Messages Received From a Port.</em>
<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>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><span class="code">port_command(Port,Data)</span></td>
<td align="left" valign="middle">Sends <span class="code">Data</span>to the port.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">port_close(Port)</span></td>
<td align="left" valign="middle">Closes the port.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">port_connect(Port,NewPid)</span></td>
<td align="left" valign="middle">Sets the port owner of <span class="code">Port</span>to <span class="code">NewPid</span>. The old port owner <span class="code">Pid</span>stays linked to the port and have to call <span class="code">unlink(Port)</span>if this is not desired.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">erlang:port_info(Port,Item)</span></td>
<td align="left" valign="middle">Returns information as specified by <span class="code">Item</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">erlang:ports()</span></td>
<td align="left" valign="middle">Returns a list of all ports on the current node.</td>
</tr>
</table>
<em>Table
14.4:
Port BIFs.</em>
<p>There are some additional BIFs that only apply to port drivers:
<span class="code">port_control/3</span> and <span class="code">erlang:port_call/3</span>.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
119
