From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- system/doc/reference_manual/ports.xml | 159 ++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 system/doc/reference_manual/ports.xml (limited to 'system/doc/reference_manual/ports.xml') diff --git a/system/doc/reference_manual/ports.xml b/system/doc/reference_manual/ports.xml new file mode 100644 index 0000000000..4847dd67cd --- /dev/null +++ b/system/doc/reference_manual/ports.xml @@ -0,0 +1,159 @@ + + + + +
+ + 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.

+
+ + -- cgit v1.2.3