20042009
Ericsson AB. All Rights Reserved.
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
Ports and Port Drivers
ports.xml
Examples of how to use ports and port drivers can be found in
Interoperability Tutorial. The BIFs mentioned are as usual
documented in erlang(3).
Ports
Ports 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.
The Erlang process which creates a port is said to be
the port owner, or the connected process 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).
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.
Port Drivers
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 port driver.
An erroneous port driver will cause the entire Erlang runtime
system to leak memory, hang or crash.
Port drivers are documented in erl_driver(4),
driver_entry(1) and erl_ddll(3).
Port BIFs
To create a port:
| open_port(PortName, PortSettings |
Returns a port identifier Portas 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 link/1and register/2. |
Port Creation BIF.
PortName is usually a tuple {spawn,Command}, where
the string Command is the name of the external program.
The external program runs outside the Erlang workspace unless a
port driver with the name Command is found. If found, that
driver is started.
PortSettings is a list of settings (options) for the port.
The list typically contains at least a tuple {packet,N}
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 binary must be included.
The port owner Pid can communicate with the port
Port 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).
Below, Data 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.
| {Pid,{command,Data}} |
Sends Datato the port. |
| {Pid,close} |
Closes the port. Unless the port is already closed, the port replies with {Port,closed}when all buffers have been flushed and the port really closes. |
| {Pid,{connect,NewPid}} |
Sets the port owner of Portto NewPid. Unless the port is already closed, the port replies with{Port,connected}to the old port owner. Note that the old port owner is still linked to the port, but the new port owner is not. |
Messages Sent To a Port.
| {Port,{data,Data}} |
Datais received from the external program. |
| {Port,closed} |
Reply to Port ! {Pid,close}. |
| {Port,connected} |
Reply to Port ! {Pid,{connect,NewPid}} |
| {'EXIT',Port,Reason} |
If the port has terminated for some reason. |
Messages Received From a Port.
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.
| port_command(Port,Data) |
Sends Datato the port. |
| port_close(Port) |
Closes the port. |
| port_connect(Port,NewPid) |
Sets the port owner of Portto NewPid. The old port owner Pidstays linked to the port and have to call unlink(Port)if this is not desired. |
| erlang:port_info(Port,Item) |
Returns information as specified by Item. |
| erlang:ports() |
Returns a list of all ports on the current node. |
Port BIFs.
There are some additional BIFs that only apply to port drivers:
port_control/3 and erlang:port_call/3.